Key : /storage/*
` | Число; ненулевое количество ответов со статусом (100-599) |
| `xxx` | Число; ненулевое количество ответов с другим кодом статуса |
| `data` | Объект; метрики данных |
| `received` | Число; суммарное количество байт, полученное от клиентов |
| `sent` | Число; суммарное количество байт, отправленное клиентам |
Пример:
```json
{
"ssl":{
"handshaked":4174,
"reuses":0,
"timedout":0,
"failed":0
},
"requests":{
"total":4327,
"processing":0,
"discarded":0
},
"responses":{
"200":4305,
"302":6,
"304":12,
"404":4
},
"data":{
"received":733955,
"sent":59207757
}
}
```
#### `/status/http/location_zones/<зона>`
Для сбора статистики в контексте [location](https://angie.software//angie/docs/configuration/modules/http/index.md#location) или [if в location](https://angie.software//angie/docs/configuration/modules/http/http_rewrite.md#if)
нужно задать директиву [status_zone](https://angie.software//angie/docs/configuration/modules/http/index.md#status-zone):
```nginx
location / {
root /usr/share/angie/html;
status_zone location_zone;
if ($request_uri ~* "^/condition") {
# ...
status_zone if_location_zone;
}
}
```
Для группировки метрик по пользовательскому значению
используйте альтернативный синтаксис.
В этом примере метрики агрегируются по [$host](https://angie.software//angie/docs/configuration/modules/http/index.md#v-host),
и каждая группа выводится как отдельная зона:
```nginx
status_zone $host zone=server_zone:5;
```
В указанной таким образом зоне разделяемой памяти
будет собираться следующая статистика:
| `requests` | Объект; метрики запросов |
|--------------|----------------------------------------------------------------------|
| `total` | Число; суммарное количество клиентских запросов |
| `discarded` | Число; суммарное количество запросов завершенных без отправки ответа |
| `responses` | Объект; метрики ответов |
| `` | Число; ненулевое количество ответов со статусом (100-599) |
| `xxx` | Число; ненулевое количество ответов с другим кодом статуса |
| `data` | Объект; метрики данных |
| `received` | Число; суммарное количество байт, полученное от клиентов |
| `sent` | Число; суммарное количество байт, отправленное клиентам |
Пример:
```json
{
"requests": {
"total": 4158,
"discarded": 0
},
"responses": {
"200": 4157,
"304": 1
},
"data": {
"received": 538200,
"sent": 177606236
}
}
```
#### `/status/http/metric_zones/<зона>`
Пользовательские метрики, созданные директивами [metric_zone](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-zone) или
[metric_complex_zone](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-complex-zone) в контексте `http`. Метрики обновляются через
директиву [metric](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#id5) или переменные модуля.
| `discarded` | Число; количество отброшенных записей метрик из-за нехватки памяти в зоне. |
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `metrics` | Объект; метрики по ключам. Для зон с одной метрикой значения — числа.
Для сложных зон значения — объекты с именами метрик. Для режима
`histogram` значения — объекты с именами бакетов. |
Если задан `discard_key` и часть записей была истекшей,
агрегированные метрики доступны под этим ключом.
Пример:
```json
{
"discarded": 3,
"metrics": {
"example.com": {
"count": 42,
"max": 8
}
"expired": {
"count": 10,
"max": 3.2
}
}
}
```
### Stream server
#### `/status/stream/server_zones/<зона>`
Для сбора статистики в контексте [server](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-server)
нужно задать директиву [status_zone](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone):
```nginx
server {
...
status_zone server_zone;
}
```
Для группировки метрик по пользовательскому значению
используйте альтернативный синтаксис.
В этом примере метрики агрегируются по [$host](https://angie.software//angie/docs/configuration/modules/http/index.md#v-host),
и каждая группа выводится как отдельная зона:
```nginx
status_zone $host zone=server_zone:5;
```
В указанной таким образом зоне разделяемой памяти
будет собираться следующая статистика:
| `ssl` | Объект; SSL-метрики.
Присутствует, если в `server` есть `listen ssl;` |
|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| `handshaked` | Число; суммарное количество успешных SSL-рукопожатий |
| `reuses` | Число; суммарное количество повторных использований SSL-сессий во время SSL-рукопожатий |
| `timedout` | Число; суммарное количество SSL-рукопожатий с истекшим таймаутом |
| `failed` | Число; суммарное количество неуспешных SSL-рукопожатий |
| `connections` | Объект; метрики соединений |
| `total` | Число; суммарное количество клиентских соединений |
| `processing` | Число; текущее количество обслуживаемых клиентских соединений |
| `discarded` | Число; суммарное количество клиентских соединений,
завершенных без создания сессии |
| `passed` | Число; суммарное количество клиентских соединений,
переданных на другой прослушивающий порт директивами `pass` |
| `sessions` | Объект; метрики сессий |
| `success` | Число; количество сессий, завершенных с кодом 200, что означает успешное завершение |
| `invalid` | Число; количество сессий, завершенных с кодом 400, случается, когда сервер не может прочитать данные от клиента, например, заголовок PROXY protocol |
| `forbidden` | Число; количество сессий, завершенных с кодом 403, когда доступ запрещен, например, ограничен для определенного адреса клиента |
| `internal_error` | Число; количество сессий, завершенных с кодом 500, внтуренняя ошибка сервера |
| `bad_gateway` | Число; количество сессий, завершенных с кодом 502, Bad Gateway, если, например, сервер в upstream недоступен или не может быть выбран |
| `service_unavailable` | Число; количество сессий, завершенных с кодом 503, Service Unavailable, если, например, доступ ограничен числом входящих соединений |
| `data` | Объект; метрики данных |
| `received` | Число; суммарное количество байт, полученное от клиентов |
| `sent` | Число; суммарное количество байт, отправленное клиентам |
Пример:
```json
{
"ssl": {
"handshaked": 24,
"reuses": 0,
"timedout": 0,
"failed": 0
},
"connections": {
"total": 24,
"processing": 1,
"discarded": 0,
"passed": 2
},
"sessions": {
"success": 24,
"invalid": 0,
"forbidden": 0,
"internal_error": 0,
"bad_gateway": 0,
"service_unavailable": 0
},
"data": {
"received": 2762947,
"sent": 53495723
}
}
```
### HTTP caches
```nginx
proxy_cache cache_zone;
proxy_cache_valid 200 10m;
```
#### `/status/http/caches/`
Для каждой зоны, сконфигурированной в [proxy_cache](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache), хранятся следующие
данные:
```json
{
"name_zone": {
"size": 0,
"cold": false,
"hit": {
"responses": 0,
"bytes": 0
},
"stale": {
"responses": 0,
"bytes": 0
},
"updating": {
"responses": 0,
"bytes": 0
},
"revalidated": {
"responses": 0,
"bytes": 0
},
"miss": {
"responses": 0,
"bytes": 0,
"responses_written": 0,
"bytes_written": 0
},
"expired": {
"responses": 0,
"bytes": 0,
"responses_written": 0,
"bytes_written": 0
},
"bypass": {
"responses": 0,
"bytes": 0,
"responses_written": 0,
"bytes_written": 0
}
}
}
```
| `size` | Число; текущий размер кэша |
|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `max_size` | Число; ограничение на максимальный размер кэша, если задано в конфигурации |
| `cold` | Логическое значение; `true`, пока загрузчик кэша подгружает данные с диска |
| `hit` | Объект; метрики возвращенных из кэша ответов ([proxy_cache_valid](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-valid)) |
| `responses` | Число; суммарное количество ответов, прочитанных из кэша |
| `bytes` | Число; суммарное количество байт, прочитанных из кэша |
| `stale` | Объект; метрики просроченных ответов, возвращенных из кэша ([proxy_cache_use_stale](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-use-stale)) |
| `responses` | Число; суммарное количество ответов, прочитанных из кэша |
| `bytes` | Число; суммарное количество байт, прочитанных из кэша |
| `updating` | Объект; метрики просроченных ответов, возвращенных из кэша, пока данные в кэше обновляются ([proxy_cache_use_stale](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-use-stale) updating) |
| `responses` | Число; суммарное количество ответов, прочитанных из кэша |
| `bytes` | Число; суммарное количество байт, прочитанных из кэша |
| `revalidated` | Объект; метрики просроченных и ревалидированных ответов, возвращенных из кэша ([proxy_cache_revalidate](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-revalidate)) |
| `responses` | Число; суммарное количество ответов, прочитанных из кэша |
| `bytes` | Число; суммарное количество байт, прочитанных из кэша |
| `miss` | Объект; метрики ответов, не найденных в кэше |
| `responses` | Число; суммарное количество соответствующих ответов |
| `bytes` | Число; суммарное количество байт, прочитанных с проксируемого сервера |
| `responses_written` | Число; суммарное количество ответов, записанных в кэш |
| `bytes_written` | Число; суммарное количество байт, записанных в кэш |
| `expired` | Объект; количество ответов, возвращенных не из кэша, т.к. просрочены |
| `responses` | Число; суммарное количество соответствующих ответов |
| `bytes` | Число; суммарное количество байт, прочитанных с проксируемого сервера |
| `responses_written` | Число; суммарное количество ответов, записанных в кэш |
| `bytes_written` | Число; суммарное количество байт, записанных в кэш |
| `bypass` | Объект; статистика ответов, возвращенных в обход кэша ([proxy_cache_bypass](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-bypass)) |
| `responses` | Число; суммарное количество соответствующих ответов |
| `bytes` | Число; суммарное количество байт, прочитанных с проксируемого сервера |
| `responses_written` | Число; суммарное количество ответов, записанных в кэш |
| `bytes_written` | Число; суммарное количество байт, записанных в кэш |
В Angie PRO при включении шардинга кэша с помощью директив
[proxy_cache_path](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path) отдельные шарды указываются как объекты-члены в объекте
`shards`:
| `shards` | Объект; его члены — отдельные шарды |
|------------|----------------------------------------------------------------------------|
| `` | Объект; представляет отдельный шард, а имя объекта — путь кэша |
| `size` | Число; текущий размер шарда |
| `max_size` | Число; максимальный размер шарда, если задан в конфигурации |
| `cold` | Логическое значение; `true`, пока загрузчик кэша подгружает данные с диска |
```json
{
"name_zone": {
"shards": {
"/path/to/shard1": {
"size": 0,
"cold": false
},
"/path/to/shard2": {
"size": 0,
"cold": false
}
}
}
```
### ACME-клиенты
#### `/status/http/acme_clients/<клиент>`
Для каждого настроенного [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) в блоке `http`
возвращается текущее состояние клиента и сертификата:
```json
{
"state": "ready",
"certificate": "valid",
"details": "The client is ready to request a certificate.",
"next_run": "|sampledateshort|T16:15:43.805Z"
}
```
| `state` | Строка; состояние ACME-клиента. Возможные значения: `ready`,
`requesting`, `disabled`, `failed`. |
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| `certificate` | Строка; состояние сертификата. Возможные значения: `valid`,
`expired`, `missing`, `mismatch`, `error`. |
| `details` | Строка; краткие сведения о последнем действии ACME. |
| `next_run` | Дата; ближайшая запланированная попытка запроса или обновления
сертификата. Не возвращается, когда `state` равно
`disabled` или `requesting`. |
### limit_conn
```nginx
limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m;
```
#### `/status/http/limit_conns/<зона>`, `/status/stream/limit_conns/<зона>`
Каждая из сконфигурированных зон: [limit_conn в http](#limit-conn) или [limit_conn в stream](https://angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#s-limit-conn) содержит следующие данные:
```json
{
"passed": 73,
"skipped": 0,
"rejected": 0,
"exhausted": 0
}
```
| `passed` | Число; суммарное количество переданных на проксируемый сервер соединений |
|-------------|-----------------------------------------------------------------------------------------------|
| `skipped` | Число; суммарное количество соединений, переданных с нулевым или превосходящим 255 байт |
| `rejected` | Число; суммарное количество соединений сверх сконфигурированного ограничения |
| `exhausted` | Число; суммарное количество соединений, сброшенных из-за переполнения хранилища зоны |
### limit_req
```nginx
limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s;
```
#### `/status/http/limit_reqs/<зона>`
Каждая из сконфигурированных зон [limit_req](#limit-req) cодержит следующие данные:
```json
{
"passed": 54816,
"skipped": 0,
"delayed": 65,
"rejected": 26,
"exhausted": 0
}
```
| `passed` | Число; суммарное количество проксированых соединений |
|-------------|-----------------------------------------------------------------------------------------------|
| `skipped` | Число; суммарное количество соединений, переданных с нулевым или превосходящим 255 байт |
| `delayed` | Число; суммарное количество задержанных соединений |
| `rejected` | Число; суммарное количество сброшенных соединений |
| `exhausted` | Число; суммарное количество соединений, сброшенных из-за переполнения хранилища зоны |
### HTTP upstream
Чтобы включить сбор следующих метрик, задайте директиву
[zone](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone)
в контексте [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream),
например:
```nginx
upstream upstream {
zone upstream 256k;
server backend.example.com service=_example._tcp resolve max_conns=5;
keepalive 4;
}
```
#### `/status/http/upstreams/`
#### Versionchanged
Изменено в версии 1.9.0: Добавлен статус `busy` у проксируемых серверов.
где — имя [апстрима](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream), в конфигурации которого указана директива [zone](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone).
```json
{
"peers": {
"192.168.16.4:80": {
"server": "backend.example.com",
"service": "_example._tcp",
"backup": false,
"weight": 5,
"state": "up",
"selected": {
"current": 2,
"total": 232
},
"max_conns": 5,
"responses": {
"200": 222,
"302": 12
},
"data": {
"sent": 543866,
"received": 27349934
},
"health": {
"fails": 0,
"unavailable": 0,
"downtime": 0
},
"sid": ""
}
},
"keepalive": 2
}
```
| `peers` | Объект; содержит метрики всех пиров апстрима во вложенных объектах,
имена которых — канонические представления адресов этих пиров.
Внутри каждого вложенного объекта: |
|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `server` | Строка; сервер, как он указан в директиве [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) |
| `service` | Строка; имя сервиса, указанное в директиве [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server), если сконфигурировано |
| `backup` | Логическое значение; `true` для backup-серверов. |
| `weight` | Число; сконфигурированный [weight](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) |
| `state` | Строка; текущее состояние пира, и какие запросы ему отправляются:
- `busy`: указывает, что число запросов на сервер
достигло ограничения, заданного [max_conns](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server),
и новые запросы на него не отправляются;
- `down`: отключен вручную, не отправляются никакие запросы;
- `recovering`: восстанавливается после сбоя
согласно [slow_start](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#slow-start),
отправляется все больше запросов;
- `unavailable`: достиг предела [max_fails](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails),
отправляются пробные клиентские запросы
с интервалом [fail_timeout](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#fail-timeout);
- `up`: работоспособен, запросы отправляются как обычно;
Дополнительные состояния в Angie PRO:
- `checking`: настроен как `essential` и проверяется,
отправляются только [проверочные запросы](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe);
- `draining`: аналогичен `down`,
но отправляются запросы сессий,
привязанных ранее через [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky);
- `unhealthy`: неработающий,
отправляются только [проверочные запросы](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe). |
| `selected` | Объект; статистика выбора пиров |
| `current` | Число; текущее количество соединений к пиру |
| `total` | Число; общее количество запросов переданных пиру |
| `last` | Строка или число; время последнего выбора пира
в формате [даты](#api-date-format) |
| `max_conns` | Число; [максимальное](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) количество одновременных активных соединений к пиру, если сконфигурировано |
| `responses` | Объект; статистика ответов |
| `` | Число; ненулевое количество ответов со статусом (100-599) |
| `xxx` | Число; ненулевое количество ответов с другим кодом статуса |
| `data` | Объект; метрики данных |
| `received` | Число; суммарное количество байт, полученное от пира |
| `sent` | Число; суммарное количество байт, отправленное пиру |
| `health` | Объект; статистика по состоянию пира |
| `fails` | Число; общее количество неудачных попыток работы с пиром |
| `unavailable` | Число; столько раз пир становился `unavailable` по достижении значения [max_fails](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) |
| `downtime` | Число; суммарное время (в миллисекундах), в течение которого пир был недоступен для выбора как `unavailable` |
| `downstart` | Строка или число; время, когда пир стал `unavailable`,
в формате [даты](#api-date-format).
Поле присутствует, только пока пир находится в состоянии
`unavailable`; в остальных случаях оно отсутствует |
| `header_time` | Число; среднее время (в миллисекундах)
получения заголовков ответа от сервера;
см. директиву [response_time_factor (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) |
| `response_time` | Число; среднее время (в миллисекундах) получения ответа от сервера;
см. директиву [response_time_factor (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) |
| `sid` | Строка; [id сервера](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve), указанный в конфигурации апстрима |
| `keepalive` | Число; текущее количество кэшированных соединений |
| `backup_switch` | Объект; содержит текущее состояние логики активного резервирования,
присутствует, если для апстрима настроен [backup_switch (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-backup-switch) |
| `active` | Число; уровень активной группы,
которая сейчас используется для балансировки запросов.
Если активная группа является основной, значение равно 0 |
| `timeout` | Число; оставшееся время ожидания в миллисекундах,
после которого балансировщик перепроверит на наличие здоровых узлов
группы с меньшим уровнем, начиная с основной,
а группы с большим уровнем не проверяются;
не отображается для основной группы (уровень 0) |
##### `health/probes` (PRO)
Если для апстрима настроены проверки [upstream_probe (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe),
то в объекте `health` также есть вложенный объект `probes`,
содержащий счетчики проверок работоспособности сервера,
а `state`, помимо значений из таблицы выше,
может принимать значения `checking` и `unhealthy`:
```json
{
"192.168.16.4:80": {
"state": "unhealthy",
"...": "...",
"health": {
"...": "...",
"probes": {
"count": 10,
"fails": 10,
"last": "|sampledateshort|T09:56:07Z"
}
}
}
}
```
Значение `checking` у `state` не учитывается в `downtime`
и означает, что сервер,
проверка которого настроена с параметром `essential`,
еще не проверялся;
значение `unhealthy` — что сервер неработающий.
Оба эти состояния также означают, что сервер не участвует в балансировке.
Детали проверок см. в описании [upstream_probe](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe).
Счетчики в `probes`:
| `count` | Число; общее количество проверок этого сервера |
|-----------|-----------------------------------------------------------------------------------|
| `fails` | Число; количество неуспешных проверок |
| `last` | Строка или число; время последней проверки
в формате [даты](#api-date-format) |
##### `queue` (PRO)
Если для апстрима настроена [очередь запросов](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-queue),
то в объекте апстрима также есть вложенный объект `queue`,
содержащий счетчики запросов в очереди:
```json
{
"queue": {
"queued": 20112,
"waiting": 1011,
"dropped": 6031,
"timedout": 560,
"overflows": 13
}
}
```
Значения счетчиков суммируются по всем рабочим процессам:
| `queued` | Число; общее количество запросов, попавших в очередь |
|-------------|--------------------------------------------------------------------------------------------------------------------|
| `waiting` | Число; текущее количество запросов в очереди |
| `dropped` | Число; общее количество запросов, удаленных из очереди из-за того,
что клиент преждевременно закрыл соединение |
| `timedout` | Число; общее количество запросов, удаленных из очереди по таймауту |
| `overflows` | Число; общее количество случаев переполнения очереди |
### Stream upstream
Чтобы включить сбор следующих метрик, задайте директиву
[zone](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone)
в контексте [upstream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream),
например:
```nginx
upstream upstream {
zone upstream 256k;
server backend.example.com service=_example._tcp resolve max_conns=5;
keepalive 4;
}
```
#### `/status/stream/upstreams/`
#### Versionchanged
Изменено в версии 1.9.0: Добавлен статус `busy` у проксируемых серверов.
Здесь — имя [апстрима](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream), в конфигурации которого
использована директива [zone](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone).
```json
{
"peers": {
"192.168.16.4:1935": {
"server": "backend.example.com",
"service": "_example._tcp",
"backup": false,
"weight": 5,
"state": "up",
"selected": {
"current": 2,
"total": 232
},
"max_conns": 5,
"data": {
"sent": 543866,
"received": 27349934
},
"health": {
"fails": 0,
"unavailable": 0,
"downtime": 0
}
}
}
}
```
| `peers` | Объект; содержит метрики всех пиров апстрима во вложенных объектах,
имена которых — канонические представления адресов этих пиров.
Внутри каждого вложенного объекта: |
|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `server` | Строка; адрес, заданный директивой [server](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) |
| `service` | Строка; имя сервиса, если оно указано в директиве [server](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) |
| `backup` | Логическое значение; `true` для backup-серверов |
| `weight` | Число; заданный для пира [вес](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) |
| `state` | Строка; текущее состояние пира, и какие запросы ему отправляются:
- `busy`: указывает, что число запросов на сервер
достигло ограничения, заданного [max_conns](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server),
и новые запросы на него не отправляются;
- `down`: отключен вручную, не отправляются никакие запросы;
- `recovering`: восстанавливается после сбоя
согласно [slow_start](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-slow-start),
отправляется все больше запросов;
- `unavailable`: достиг предела [max_fails](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails),
отправляются пробные клиентские запросы
с интервалом [fail_timeout](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-fail-timeout);
- `up`: работоспособен, запросы отправляются как обычно.
Дополнительные состояния в Angie PRO:
- `checking`: настроен как `essential` и проверяется,
отправляются только [проверочные запросы](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe);
- `draining`: аналогичен `down`,
но отправляются запросы сессий,
привязанных ранее через [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky);
- `unhealthy`: неработающий,
отправляются только [проверочные запросы](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe). |
| `selected` | Объект; статистика выбора этого пира для подключения |
| `current` | Число; текущее количество подключений к пиру |
| `total` | Число; общее количество подключений, направленных этому пиру |
| `last` | Строка или число; время, когда пир был выбран в последний раз,
в формате [даты](#api-date-format) |
| `max_conns` | Число;
[максимальное](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server)
количество одновременных активных подключений к пиру, если оно задано |
| `data` | Объект; статистика передачи данных |
| `received` | Число; общее количество байт, полученное от пира |
| `sent` | Число; общее количество байт, отправленное пиру |
| `health` | Объект; статистика по состоянию пира |
| `fails` | Число; общее количество неудачных попыток связаться с пиром |
| `unavailable` | Число; общее количество переходов в состояние `unavailable`
по достижении значения [max_fails](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails) |
| `downtime` | Число; общее время в миллисекундах,
в течение которого пир находился в состоянии `unavailable`
(недоступен для выбора) |
| `downstart` | Строка или число; время, когда пир последний раз стал `unavailable`,
в формате [даты](#api-date-format).
Поле присутствует, только пока пир находится в состоянии
`unavailable`; в остальных случаях оно отсутствует |
| `connect_time` | Число; среднее время (в миллисекундах)
установления соединения с сервером;
см. директиву [response_time_factor (PRO)](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) |
| `first_byte_time` | Число; среднее время (в миллисекундах)
получения первого байта ответа от сервера;
см. директиву [response_time_factor (PRO)](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) |
| `last_byte_time` | Число; среднее время (в миллисекундах)
получения полного ответа от сервера;
см. директиву [response_time_factor (PRO)](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) |
| `backup_switch`
(PRO 1.10.0+) | Объект; содержит текущее состояние логики активного резервирования,
присутствует, если для апстрима настроен [backup_switch (PRO)](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-backup-switch) |
| `active` | Число; уровень активной группы,
которая сейчас используется для балансировки запросов.
Если активная группа является основной, значение равно 0 |
| `timeout` | Число; оставшееся время ожидания в миллисекундах,
после которого балансировщик перепроверит на наличие здоровых узлов
группы с меньшим уровнем, начиная с основной,
а группы с большим уровнем не проверяются;
не отображается для основной группы (уровень 0) |
Если в Angie PRO для апстрима настроены проверки [upstream_probe (PRO)](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe),
то в объекте `health` также есть вложенный объект `probes`,
содержащий счетчики проверок работоспособности сервера,
а `state`, помимо значений из таблицы выше,
может принимать значения `checking` и `unhealthy`:
```json
{
"192.168.16.4:80": {
"state": "unhealthy",
"...": "...",
"health": {
"...": "...",
"probes": {
"count": 2,
"fails": 2,
"last": "|sampledateshort|T11:03:54Z"
}
}
}
}
```
Значение `checking` у `state` означает, что сервер,
проверка которого настроена с параметром `essential`,
еще не проверялся;
значение `unhealthy` — что сервер неработающий.
Оба эти состояния также означают, что сервер не участвует в балансировке.
Детали проверок см. в описании [upstream_probe](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe).
Счетчики в `probes`:
| `count` | Число; общее количество проверок этого сервера |
|-----------|-----------------------------------------------------------------------------------|
| `fails` | Число; количество неуспешных проверок |
| `last` | Строка или число; время последней проверки
в формате [даты](#api-date-format) |
## API динамической конфигурации (PRO)
В составе API есть раздел `/config`, позволяющий динамически менять
конфигурацию Angie в формате JSON
с помощью HTTP-запросов `PUT`, `PATCH` и `DELETE`.
Все изменения атомарны: новые настройки применяются целиком
либо не применяются вовсе.
При ошибке Angie сообщит, в чем причина.
### Подразделы `/config`
Cейчас в разделе `/config` доступна настройка отдельных серверов в
составе апстримов для модулей [HTTP](#api-config-http-upstreams-servers)
и [stream](#api-config-stream-upstreams-servers); число настроек, к
которым применима динамическая конфигурация, планомерно увеличивается.
#### `/config/http/upstreams//servers/<имя>`
Позволяет настраивать отдельные серверы в составе апстрима,
в том числе добавлять новые и удалять настроенные.
Параметры в составе пути URI:
| `` | Имя блока `upstream`;
чтобы настраивать его через `/config`,
в нем должна быть задана директива [zone](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone),
определяющая зону разделяемой памяти. |
|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `<имя>` | Имя конкретного сервера в составе указанного ``;
задается в формате `@`, где:
- `@` — необязательная часть,
задающая имя сервиса в целях разрешения SRV-записей.
- `` — доменное имя сервиса (при наличии resolve)
или IP-адрес; также можно указать порт. |
Например, для следующей конфигурации:
```nginx
upstream backend {
server backend.example.com service=_http._tcp resolve;
server 127.0.0.1;
zone backend 1m;
}
```
Допустимы такие имена серверов:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/_http._tcp@backend.example.com/
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/127.0.0.1:80/
```
Этот подраздел API позволяет задавать параметры `weight`,
`max_conns`, `max_fails`, `fail_timeout`, `slow_start`, `backup`,
`down` и `sid`, описанные в разделе [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server).
#### NOTE
Отдельного параметра `drain` (PRO) здесь нет;
включить режим `drain` можно,
задав для `down` строковое значение `drain`:
```console
$ curl -X PUT -d \"drain\" \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/down
```
Пример:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on
```
```json
{
"weight": 1,
"max_conns": 0,
"max_fails": 1,
"fail_timeout": 10,
"slow_start": 0,
"backup": true,
"down": false,
"sid": ""
}
```
Фактически доступны будут только те параметры, которые поддерживает
текущий метод балансировки нагрузки [апстрима](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream).
Так, если апстрим настроен с методом балансировки `random`:
```nginx
upstream backend {
zone backend 256k;
server backend.example.com resolve max_conns=5;
random;
}
```
То добавить в него новый сервер с параметром `backup` невозможно:
```console
$ curl -X PUT -d '{ "backup": true }' \
http://127.0.0.1/config/http/upstreams/backend/servers/backend1.example.com
```
```json
{
"error": "FormatError",
"description": "The \"backup\" field is unknown."
}
```
#### NOTE
Даже с совместимым методом балансировки параметр `backup`
можно задать лишь при добавлении нового сервера.
#### `/config/stream/upstreams//servers/<имя>`
Позволяет настраивать отдельные серверы в составе апстрима,
в том числе добавлять новые и удалять настроенные.
Параметры в составе пути URI:
| `` | Имя блока `upstream`;
чтобы настраивать его через `/config`,
в нем должна быть задана директива [zone](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone),
определяющая зону разделяемой памяти. |
|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `<имя>` | Имя конкретного сервера в составе указанного ``;
задается в формате `@`, где:
- `@` — необязательная часть,
задающая имя сервиса в целях разрешения SRV-записей.
- `` — доменное имя сервиса (при наличии resolve)
или IP-адрес; также можно указать порт. |
Например, для следующей конфигурации:
```nginx
upstream backend {
server backend.example.com:8080 service=_example._tcp resolve;
server 127.0.0.1:12345;
zone backend 1m;
}
```
Допустимы такие имена серверов:
```console
$ curl http://127.0.0.1/config/stream/upstreams/backend/servers/_example._tcp@backend.example.com:8080/
$ curl http://127.0.0.1/config/stream/upstreams/backend/servers/127.0.0.1:12345/
```
Этот подраздел API позволяет задавать параметры `weight`,
`max_conns`, `max_fails`, `fail_timeout`, `slow_start`, `backup` и
`down`, описанные в разделе [server](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server).
#### NOTE
Отдельного параметра `drain` (PRO) здесь нет;
включить режим `drain` можно,
задав для `down` строковое значение `drain`:
```console
$ curl -X PUT -d \"drain\" \
http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com/down
```
Пример:
```console
curl http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com?defaults=on
```
```json
{
"weight": 1,
"max_conns": 0,
"max_fails": 1,
"fail_timeout": 10,
"slow_start": 0,
"backup": true,
"down": false,
}
```
Фактически доступны будут только те параметры, которые поддерживает
текущий метод балансировки нагрузки [апстрима](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream).
Так, если апстрим настроен с методом балансировки `random`:
```nginx
upstream backend {
zone backend 256k;
server backend.example.com resolve max_conns=5;
random;
}
```
То добавить в него новый сервер с параметром `backup` невозможно:
```console
$ curl -X PUT -d '{ "backup": true }' \
http://127.0.0.1/config/stream/upstreams/backend/servers/backend1.example.com
```
```json
{
"error": "FormatError",
"description": "The \"backup\" field is unknown."
}
```
#### NOTE
Даже с совместимым методом балансировки параметр `backup`
можно задать лишь при добавлении нового сервера.
При удалении серверов можно установить аргумент
`connection_drop=<значение>` (PRO), чтобы переопределить настройки
[proxy_connection_drop](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-connection-drop):
```console
$ curl -X DELETE \
http://127.0.0.1/config/stream/upstreams/backend/servers/backend1.example.com?connection_drop=off
$ curl -X DELETE \
http://127.0.0.1/config/stream/upstreams/backend/servers/backend2.example.com?connection_drop=on
$ curl -X DELETE \
http://127.0.0.1/config/stream/upstreams/backend/servers/backend3.example.com?connection_drop=1000
```
### HTTP-методы
Рассмотрим семантику каждого из применимых к этому разделу HTTP-методов
на примере следующей конфигурации апстрима:
```nginx
http {
# ...
upstream backend {
zone upstream 256k;
server backend.example.com resolve max_conns=5;
# ...
}
server {
# ...
location /config/ {
api /config/;
allow 127.0.0.1;
deny all;
}
}
}
```
#### GET
HTTP-метод `GET` позволяет запросить сущность по любому существующему пути
в пределах `/config` так же, как это делается в других разделах API.
Например, для ветки серверов апстрима
`/config/http/upstreams/backend/servers/`
допустимы такие запросы:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_conns
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
$ curl http://127.0.0.1/config/http/upstreams/backend/servers
$ # ...
$ curl http://127.0.0.1/config
```
Получить параметры по умолчанию можно с аргументом `defaults=on`:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers?defaults=on
```
```json
{
"backend.example.com": {
"weight": 1,
"max_conns": 5,
"max_fails": 1,
"fail_timeout": 10,
"slow_start": 0,
"backup": false,
"down": false,
"sid": ""
}
}
```
#### PUT
HTTP-метод `PUT` позволяет создать новую JSON-сущность по указанному пути
или *полностью* заменить существующую.
Например, чтобы добавить не заданный ранее параметр `max_fails`
у сервера `backend.example.com` в апстриме `backend`:
```console
$ curl -X PUT -d '2' \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails
```
```json
{
"success": "Updated",
"description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was updated with replacing."
}
```
Проверим изменения:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```
```json
{
"max_conns": 5,
"max_fails": 2
}
```
#### DELETE
HTTP-метод `DELETE` удаляет *ранее заданные* настройки по указанному пути;
при этом восстанавливаются значения по умолчанию, если они есть.
Например, чтобы удалить измененный ранее параметр `max_fails`
у сервера `backend.example.com` в апстриме `backend`:
```console
$ curl -X DELETE \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails
```
```console
{
"success": "Reset",
"description": "Configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was reset to default."
}
```
Проверим изменения с аргументом `defaults=on`:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on
```
```json
{
"weight": 1,
"max_conns": 5,
"max_fails": 1,
"fail_timeout": 10,
"slow_start": 0,
"backup": false,
"down": false,
"sid": ""
}
```
Параметр `max_fails` вернулся к значению по умолчанию.
При удалении серверов можно установить аргумент
`connection_drop=<значение>` (PRO), чтобы переопределить настройки
[proxy_connection_drop](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-connection-drop), [grpc_connection_drop](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-connection-drop),
[fastcgi_connection_drop](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-connection-drop), [scgi_connection_drop](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-connection-drop) и
[uwsgi_connection_drop](https://angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-connection-drop):
```console
$ curl -X DELETE \
http://127.0.0.1/config/http/upstreams/backend/servers/backend1.example.com?connection_drop=off
$ curl -X DELETE \
http://127.0.0.1/config/http/upstreams/backend/servers/backend2.example.com?connection_drop=on
$ curl -X DELETE \
http://127.0.0.1/config/http/upstreams/backend/servers/backend3.example.com?connection_drop=1000
```
#### PATCH
HTTP-метод `PATCH` позволяет создать новую сущность по указанному пути
либо частично заменить или дополнить существующую
([RFC 7386](https://datatracker.ietf.org/doc/html/rfc7396)),
отправив в данных JSON-определение.
Метод работает так: если сущности, указанные в новом определении, уже есть
в конфигурации, они будут перезаписаны; если их нет, то они будут добавлены.
Например, чтобы поменять значение параметра `down` у сервера
`backend.example.com` в апстриме `backend`,
оставив прочее без изменений:
```console
$ curl -X PATCH -d '{ "down": true }' \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```
```json
{
"success": "Updated",
"description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging."
}
```
Проверим изменения:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```
```json
{
"max_conns": 5,
"down": true
}
```
Обратите внимание, что переданный с запросом `PATCH` JSON-объект *слился*
с уже существующим, а не заменил его целиком, как было бы с `PUT`.
Особый случай представляют значения `null`; они используются для удаления
отдельных элементов конфигурации в ходе такого слияния.
#### NOTE
Такое удаление аналогично действию `DELETE`;
в частности, восстанавливаются значения по умолчанию.
Например, чтобы удалить добавленный ранее параметр `down`
и одновременно с этим изменить `max_conns`:
```console
$ curl -X PATCH -d '{ "down": null, "max_conns": 6 }' \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```
```json
{
"success": "Updated",
"description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging."
}
```
Проверим изменения:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```
```json
{
"max_conns": 6
}
```
Параметр `down`, для которого было передано значение `null`, удален;
значение `max_conns` изменено.
# https://angie.software/angie/docs/configuration/modules/http/http_auth_basic.md
# Auth Basic
Позволяет ограничить доступ к ресурсам с проверкой имени и пароля пользователя по протоколу "HTTP Basic Authentication".
Ограничить доступ можно также по [адресу](https://angie.software//angie/docs/configuration/modules/http/http_access.md#http-access) или по [результату подзапроса](https://angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request). Одновременное ограничение доступа по адресу и паролю управляется директивой [satisfy](https://angie.software//angie/docs/configuration/modules/http/index.md#satisfy).
## Пример конфигурации
```nginx
location / {
auth_basic "closed site";
auth_basic_user_file conf/htpasswd;
}
```
## Директивы
### auth_basic
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_basic` строка | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `auth_basic off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, limit_except |
Включает проверку имени и пароля пользователя по протоколу "HTTP Basic Authentication". Заданный параметр используется в качестве realm. В значении параметра допустимо использование переменных.
| `off` | отменяет действие унаследованной с предыдущего уровня конфигурации директивы auth_basic |
|---------|-------------------------------------------------------------------------------------------|
### auth_basic_user_file
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_basic_user_file` файл; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, limit_except |
Задает файл, в котором хранятся имена и пароли пользователей. Формат файла следующий:
```none
# комментарий
имя1:пароль1
имя2:пароль2:комментарий
имя3:пароль3
```
В имени файла можно использовать переменные.
Поддерживаются следующие типы паролей:
* зашифрованные функцией crypt(); могут быть созданы с помощью утилиты `htpasswd` из дистрибутива HTTP-сервера Apache или команды "openssl passwd";
* хэшированные с помощью алгоритма, основанного на MD5, по версии Apache (apr1); могут быть созданы теми же инструментами;
* заданные согласно синтаксису "{схема}данные" как описано в [RFC 2307](https://datatracker.ietf.org/doc/html/rfc2307#section-5.3); в настоящий момент реализованы схемы PLAIN (в качестве примера, не следует применять), SHA (простое SHA-1 хэширование, не следует применять) и SSHA (SHA-1 хэширование с солью, используется в некоторых программах, в частности OpenLDAP и Dovecot).
#### WARNING
Поддержка схемы SHA была добавлена лишь для облегчения процесса миграции файлов паролей с других веб-серверов. Ее не следует применять для новых паролей, т.к. используемое при этом SHA-1 хэширование без соли уязвимо к взлому при помощи [радужных таблиц](http://en.wikipedia.org/wiki/Rainbow_attack).
# https://angie.software/angie/docs/configuration/modules/http/http_auth_request.md
# Auth Request
Предоставляет возможность авторизации клиента, основанной на результате подзапроса. Если подзапрос возвращает код ответа 2xx, доступ разрешается. Если 401 или 403 — доступ запрещается с соответствующим кодом ошибки. Любой другой код ответа, возвращаемый подзапросом, считается ошибкой.
При ошибке 401 клиенту также передается заголовок `WWW-Authenticate` из ответа подзапроса.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_auth_request_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
Модуль может быть скомбинирован с другими модулями доступа, такими как [Access](https://angie.software//angie/docs/configuration/modules/http/http_access.md#http-access) и [Auth Basic](https://angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic) с помощью директивы [satisfy](https://angie.software//angie/docs/configuration/modules/http/index.md#satisfy).
## Пример конфигурации
```nginx
location /private/ {
auth_request /auth;
# ...
}
location = /auth {
proxy_pass ...;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
}
```
## Директивы
### auth_request
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_request` `uri` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `auth_request off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Включает авторизацию, основанную на результате выполнения подзапроса, и задает URI, на который будет отправлен подзапрос.
### auth_request_set
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_request_set` $переменная значение; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Устанавливает переменную в запросе в заданное значение после завершения запроса авторизации. Значение может содержать переменные из запроса авторизации, например, $upstream_http_\*.
# https://angie.software/angie/docs/configuration/modules/http/http_autoindex.md
# AutoIndex
Обслуживает запросы, оканчивающиеся косой чертой (`/`), и выдает листинг каталога. Обычно запрос попадает к модулю `AutoIndex`, когда модуль [Index](https://angie.software//angie/docs/configuration/modules/http/http_index.md#http-index) не нашел индексный файл.
## Пример конфигурации
```nginx
location / {
autoindex on;
}
```
## Директивы
### autoindex
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `autoindex` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `autoindex off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает вывод листинга каталога.
### autoindex_exact_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `autoindex_exact_size` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `autoindex_exact_size on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Для [формата](#autoindex-format) HTML определяет, как выводить размеры файлов в листинге каталога: точно или округляя до килобайт, мегабайт и гигабайт.
### autoindex_format
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `autoindex_format` `html` | `xml` | `json` | `jsonp`; |
|------------------------------------------------------------------------------------------|---------------------------------------------------------|
| По умолчанию | `autoindex_format html;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает формат вывода листинга каталога.
При использовании формата JSONP имя callback-функции задается в аргументе запроса `callback`. Если аргумент отсутствует или имеет пустое значение, то используется формат JSON.
Вывод в формате XML может быть преобразован при помощи модуля [XSLT](https://angie.software//angie/docs/configuration/modules/http/http_xslt.md#http-xslt).
### Форматы вывода
Поля объекта в ответах содержат следующие данные:
| Поле | Описание |
|---------|------------------------------------------------------------------------------------------------|
| `name` | Имя файла или каталога |
| `type` | Тип объекта: `file` или `directory` |
| `size` | Размер объекта согласно [autoindex_exact_size](#autoindex-exact-size);
для каталогов — `0` |
| `mtime` | Время последнего изменения в формате Unix time |
HTML
```html
Index of /files/
Index of /files/
../
example.txt 12-Jun-2025 14:21 1234
image.png 12-Jun-2025 14:21 4321
```
XML
```xml
example.txt
file
1234
2025-06-12T14:21:00Z
image.png
file
4321
2025-06-12T14:21:00Z
```
JSON
```json
[
{
"name": "example.txt",
"type": "file",
"size": 1234,
"mtime": "2025-06-12T14:21:00Z"
},
{
"name": "image.png",
"type": "file",
"size": 4321,
"mtime": "2025-06-12T14:21:00Z"
}
]
```
JSONP
```javascript
callback([
{
"name": "example.txt",
"type": "file",
"size": 1234,
"mtime": "2025-06-12T14:21:00Z"
},
{
"name": "image.png",
"type": "file",
"size": 4321,
"mtime": "2025-06-12T14:21:00Z"
}
]);
```
### autoindex_localtime
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `autoindex_localtime` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `autoindex_localtime off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Для [формата](#autoindex-format) HTML определяет, в какой временной зоне выводить время в листинге каталога: в локальной или в UTC.
# https://angie.software/angie/docs/configuration/modules/http/http_browser.md
# Browser
Создает переменные, значения которых зависят от значения поля `User-Agent` в заголовке запроса.
## Переменные
### `$modern_browser`
равна значению, заданному директивой [modern_browser_value](#modern-browser-value), если браузер опознан как современный;
### `$ancient_browser`
равна значению, заданному директивой [ancient_browser_value](#ancient-browser-value), если браузер опознан как устаревший;
### `$msie`
равна "1", если браузер опознан как MSIE любой версии.
## Пример конфигурации
### Выбор индексного файла:
```nginx
modern_browser_value "modern.";
modern_browser msie 5.5;
modern_browser gecko 1.0.0;
modern_browser opera 9.0;
modern_browser safari 413;
modern_browser konqueror 3.0;
index index.${modern_browser}html index.html;
```
### Перенаправление для старых браузеров:
```nginx
modern_browser msie 5.0;
modern_browser gecko 0.9.1;
modern_browser opera 8.0;
modern_browser safari 413;
modern_browser konqueror 3.0;
modern_browser unlisted;
ancient_browser Links Lynx netscape4;
if ($ancient_browser) {
rewrite ^ /ancient.html;
}
```
## Директивы
### ancient_browser
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ancient_browser` строка ...; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает подстроки, при нахождении которых в поле `User-Agent` заголовка запроса браузер считается устаревшим. Специальная строка "netscape4" соответствует регулярному выражению "^Mozilla/[1-4]".
### ancient_browser_value
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ancient_browser_value` строка; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `ancient_browser_value 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает значение для переменных [$ancient_browser](#v-ancient-browser).
### modern_browser
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `modern_browser` браузер версия;
`modern_browser` `unlisted`; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает версию браузера, начиная с которой он считается современным. В качестве браузера можно задать msie, gecko (браузеры, созданные на основе Mozilla), opera, safari или konqueror.
Версии можно задать в форматах X, X.X, X.X.X или X.X.X.X. Максимальные значения для каждого из форматов соответственно — 4000, 4000.99, 4000.99.99 и 4000.99.99.99.
Специальное значение `unlisted` указывает считать современным браузер, не описанный директивами modern_browser и [ancient_browser](#id6). В противном случае неперечисленный браузер будет считаться устаревшим. Если в заголовке запроса нет поля `User-Agent`, то браузер считается неперечисленным.
### modern_browser_value
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `modern_browser_value` строка; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `modern_browser_value 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает значение для переменных [$modern_browser](#v-modern-browser).
# https://angie.software/angie/docs/configuration/modules/http/http_charset.md
# Charset
Добавляет указанную кодировку в поле `Content-Type` заголовка ответа. Кроме того, модуль может перекодировать данные из одной кодировки в другую с некоторыми ограничениями:
* перекодирование осуществляется только в одну сторону — от сервера к клиенту,
* перекодироваться могут только однобайтные кодировки
* или однобайтные кодировки в UTF-8 и обратно.
## Пример конфигурации
```nginx
include conf/koi-win;
charset windows-1251;
source_charset koi8-r;
```
## Директивы
### charset
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `charset` кодировка | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `charset off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Добавляет указанную кодировку в поле `Content-Type` заголовка ответа. Если эта кодировка отличается от указанной в директиве [source_charset](#source-charset), то выполняется перекодирование.
Параметр `off` отменяет добавление кодировки в поле `Content-Type` заголовка ответа.
Кодировка может быть задана с помощью переменной:
```nginx
charset $charset;
```
В этом случае необходимо, чтобы все возможные значения переменной присутствовали хотя бы один раз в любом месте конфигурации в виде директив [charset_map](#charset-map), charset или [source_charset](#source-charset). Для кодировок utf-8, windows-1251 и koi8-r для этого достаточно включить в конфигурацию файлы conf/koi-win, conf/koi-utf и conf/win-utf. Для других кодировок можно просто сделать фиктивную таблицу перекодировки, например:
```nginx
charset_map iso-8859-5 _ { }
```
Кроме того, кодировка может быть задана в поле `X-Accel-Charset` заголовка ответа. Эту возможность можно запретить с помощью директив [proxy_ignore_headers](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ignore-headers), [fastcgi_ignore_headers](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-ignore-headers), [uwsgi_ignore_headers](https://angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-ignore-headers), [scgi_ignore_headers](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-ignore-headers) и [grpc_ignore_headers](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-ignore-headers).
### charset_map
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `charset_map` кодировка1 кодировка2 { ... } |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Описывает таблицу перекодирования из одной кодировки в другую. Таблица для обратного перекодирования строится на основании тех же данных. Коды символов задаются в шестнадцатеричном виде. Неописанные символы в пределах 80-FF заменяются на "?". При перекодировании из UTF-8 символы, отсутствующие в однобайтной кодировке, заменяются на "&#XXXX;".
Пример:
```nginx
charset_map koi8-r windows-1251 {
C0 FE ; # small yu
C1 E0 ; # small a
C2 E1 ; # small b
C3 F6 ; # small ts
}
```
При описании таблицы перекодирования в UTF-8, коды кодировки UTF-8 должны быть указаны во второй колонке, например:
```nginx
charset_map koi8-r utf-8 {
C0 D18E ; # small yu
C1 D0B0 ; # small a
C2 D0B1 ; # small b
C3 D186 ; # small ts
}
```
Полные таблицы преобразования из koi8-r в windows-1251 и из koi8-r и windows-1251 в utf-8 входят в дистрибутив и находятся в файлах conf/koi-win, conf/koi-utf и conf/win-utf.
### charset_types
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `charset_types` mime-тип ...; |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
| По умолчанию | `charset_types text/html text/xml text/plain text/vnd.wap.wml application/javascript application/rss+xml;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает работу модуля в ответах с указанными MIME-типами в дополнение к `text/html`. Специальное значение `*` соответствует любому MIME-типу.
### override_charset
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `override_charset` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `override_charset off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Определяет, выполнять ли перекодирование для ответов, полученных от проксированного сервера или от FastCGI/uwsgi/SCGI/gRPC-сервера, если в ответах уже указана кодировка в поле `Content-Type` заголовка ответа. Если перекодирование разрешено, то в качестве исходной кодировки используется кодировка, указанная в полученном ответе.
#### NOTE
Если ответ был получен в подзапросе, то, независимо от значения директивы override_charset, всегда выполняется перекодирование из кодировки ответа в кодировку основного запроса.
### source_charset
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `source_charset` кодировка; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Задает исходную кодировку ответа. Если эта кодировка отличается от указанной в директиве [charset](#id3), то выполняется перекодирование.
# https://angie.software/angie/docs/configuration/modules/http/http_dav.md
# DAV
Предназначен для автоматизации задач управления файлами на сервере по протоколу WebDAV. Модуль обрабатывает HTTP- и WebDAV-методы PUT, DELETE, MKCOL, COPY и MOVE.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_dav_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
#### NOTE
WebDAV-клиенты, которые требуют для работы дополнительных WebDAV-методов, не будут работать с этим модулем.
## Пример конфигурации
```nginx
location / {
root /data/www;
client_body_temp_path /data/client_temp;
dav_methods PUT DELETE MKCOL COPY MOVE;
create_full_put_path on;
dav_access group:rw all:r;
limit_except GET {
allow 192.168.1.0/32;
deny all;
}
}
```
## Директивы
### create_full_put_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `create_full_put_path` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `create_full_put_path off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
По спецификации WebDAV-метод PUT может создавать файл только в уже существующем каталоге. Данная директива разрешает создавать все необходимые промежуточные каталоги.
### dav_access
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `dav_access` пользователи:права ...; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `dav_access user:rw;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает права доступа для создаваемых файлов и каталогов, например,
```nginx
dav_access user:rw group:rw all:r;
```
Если заданы какие-либо права для group или all, то права для user указывать необязательно:
```nginx
dav_access group:rw all:r;
```
### dav_methods
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `dav_methods` `off` | метод ...; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `dav_methods off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает указанные HTTP- и WebDAV-методы. Параметр `off` запрещает все методы, обрабатываемые данным модулем. Поддерживаются следующие методы: PUT, DELETE, MKCOL, COPY и MOVE.
Файл, загружаемый методом PUT, записывается во временный файл, а потом этот файл переименовывается. Временный файл и его постоянное место хранения могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешевой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой системе, что и каталог с временными файлами, задаваемый директивой [client_body_temp_path](https://angie.software//angie/docs/configuration/modules/http/index.md#client-body-temp-path) для данного `location`.
При создании файла с помощью метода PUT можно задать дату модификации, передав ее в поле заголовка `Date`.
### min_delete_depth
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `min_delete_depth` число; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `min_delete_depth 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает методу DELETE удалять файлы при условии, что число элементов в пути запроса не меньше заданного. Например, директива
```nginx
min_delete_depth 4;
```
разрешает удалять файлы по запросам
```console
/users/00/00/name
/users/00/00/name/pic.jpg
/users/00/00/page.html
```
и запрещает удаление
```console
/users/00/00
```
# https://angie.software/angie/docs/configuration/modules/http/http_docker.md
# Docker
#### Versionadded
Добавлено в версии 1.10.0.
Модуль обеспечивает динамическую настройку групп проксируемых серверов
как в [HTTP-](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream), так и в [потоковых](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream)
контекстах на основании Docker-меток контейнеров.
Для работы функции в группе должна быть настроена зона разделяемой памяти
(см. описание `zone` для [http](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) и [stream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone)).
#### NOTE
Модуль поддерживает работу как с Docker, так и с его аналогами,
например Podman, которые реализуют совместимый API.
Рекомендуемая версия Podman — 4.9.3 и выше.
Модуль подключается к демону Docker через API,
способ взаимодействия с которым задается директивой [docker_endpoint](#docker-endpoint).
Получив список запущенных контейнеров,
Angie анализирует их на наличие подходящих [меток](#docker-labels).
Если в описании контейнера присутствует метка с портом,
то адрес и порт такого контейнера,
а также параметры из других меток этого контейнера,
автоматически добавляются в соответствующий блок `upstream`
конфигурации Angie.
#### NOTE
Один и тот же контейнер можно добавить в несколько `upstream`-групп.
Для этого достаточно указать несколько наборов меток
с разными именами групп и портами.
Это особенно полезно,
если в контейнере работают несколько различных сервисов на разных портах —
каждый сервис можно ассоциировать со своей группой.
Затем модуль подписывается на события жизненного цикла контейнеров
и начинает обновлять конфигурацию проксируемых серверов без перезагрузки Angie:
- при запуске контейнера с подходящими метками
его внутренний IP-адрес добавляется в заданную группу;
- при остановке или удалении контейнера
он автоматически удаляется из группы;
- при приостановке контейнера командой **docker pause**
сервер помечается как `down`,
а при **docker unpause** — как `up`.
## Пример конфигурации
Директивы самого модуля всегда находятся в контексте `http`,
но группы проксируемых серверов могут быть определены
как в контексте `http`, так и в потоковом контексте `stream`.
Пример конфигурации для `http`:
```nginx
http {
# Примеры вариантов подключения:
# docker_endpoint http://127.0.0.1:2375;
# docker_endpoint https://127.0.0.1:2376;
docker_endpoint unix:/var/run/docker.sock;
# максимальный размер буфера ответа Docker (необязательно)
# docker_max_object_size 128k;
upstream u {
zone z 1m; # необходима зона разделяемой памяти
}
server {
listen 80;
server_name example.com;
location / {
proxy_pass http://u;
}
}
}
```
Аналогично в потоковом контексте:
```nginx
http {
# Примеры вариантов подключения:
# docker_endpoint http://127.0.0.1:2375;
# docker_endpoint https://127.0.0.1:2376;
docker_endpoint unix:/var/run/docker.sock;
# максимальный размер буфера ответа Docker (необязательно)
# docker_max_object_size 128k;
}
stream {
upstream u {
zone z 1m;
}
server {
listen 12345;
proxy_pass u;
}
}
```
Получив событие для контейнера,
Angie ищет метки вида
`angie.http.upstreams.<имя>.port=<порт>` (для HTTP-контекста)
или `angie.stream.upstreams.<имя>.port=<порт>` (для потокового контекста).
При наличии метки адрес контейнера в указанной Docker-сети
(или первой доступной, если метка `angie.network` не задана)
добавляется в соответствующую группу проксируемых серверов.
Если контейнер останавливается или удаляется, сервер убирается из группы;
если контейнер приостанавливается, сервер помечается как `down`.
Фрагмент файла `docker-compose.yml` с метками, которые распознает Angie:
```yaml
services:
myapp:
image: myapp:latest
labels:
- "angie.http.upstreams.u.port=8080"
- "angie.network=my_bridge"
- "angie.http.upstreams.u.weight=2"
- "angie.http.upstreams.u.max_conns=50"
- "angie.http.upstreams.u.max_fails=3"
- "angie.http.upstreams.u.fail_timeout=10s"
- "angie.http.upstreams.u.backup=true"
```
## Метки
Метки задают параметры сервера в группе проксируемых серверов
аналогично аргументам директивы `server`:
| Метка | Назначение |
|---------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
| `angie.(http|stream).upstreams.<имя>.port=<порт>` *(обязательная)* | Порт контейнера, по которому будет обращаться Angie;
: сам контейнер добавляется в группу с именем `<имя>`. |
| `angie.network=` | Имя Docker-сети, из которой следует брать IP-адрес контейнера. |
| `angie.(http|stream).upstreams.<имя>.weight=` | Значение параметра `weight`. |
| `angie.(http|stream).upstreams.<имя>.max_conns=` | Максимальное число одновременных соединений (`max_conns`). |
| `angie.(http|stream).upstreams.<имя>.max_fails=` | Порог неудачных попыток (`max_fails`). |
| `angie.(http|stream).upstreams.<имя>.fail_timeout=` | Интервал для подсчета неудачных попыток (`fail_timeout`). |
| `angie.(http|stream).upstreams.<имя>.backup=true|false` | Помечает сервер как `backup`. |
| `angie.(http|stream).upstreams.<имя>.sid=<строка>` | Устанавливает пользовательский идентификатор сервера (`sid`),
для проксируемого сервера. |
| `angie.(http|stream).upstreams.<имя>.slow_start=<время>` | Включает режим `slow_start` с настраиваемым периодом времени. |
## Директивы
### docker_endpoint
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `docker_endpoint` `URL`; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Указывает способ подключения к демону Docker и включает отслеживание
событий контейнеров.
Поддерживаются следующие варианты:
| `unix:/var/run/docker.sock` | Подключение через Unix-сокет (например, `/var/run/docker.sock`). |
|-----------------------------------------|--------------------------------------------------------------------|
| `http://host:port`, `https://host:port` | Подключение по HTTP или HTTPS к удаленному Docker API. |
Подключение можно дополнительно настроить с помощью контекста [client](https://angie.software//angie/docs/configuration/modules/http/index.md#client),
куда модуль добавляет два именованных `location`:
- `@docker_events` используется для получения событий контейнеров;
- `@docker_containers` — для получения информации о контейнерах.
По умолчанию в них задана директива [proxy_pass](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass)
с адресом подключения и рядом других оптимальных настроек по умолчанию,
к которым можно добавить другие настройки из модуля [Proxy](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy).
Если директива задана,
Angie открывает соединение с Docker указанным способом,
запрашивает список запущенных контейнеров,
анализирует их метки и обрабатывает все последующие события контейнеров,
добавляя или удаляя серверы в группах проксируемых серверов согласно меткам.
### docker_max_object_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `docker_max_object_size` `<размер>`; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| Значение по умолчанию | `64k` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает максимальный размер буфера,
который используется как для JSON-ответов на запросы к Docker,
так и для потока событий контейнеров.
- Для обычных запросов (версия API, список контейнеров, информация о контейнере):
весь ответ должен поместиться в буфер, иначе возникнет ошибка.
- Для событий контейнеров используется потоковая обработка
с переиспользованием буфера,
что позволяет обрабатывать неограниченный поток событий.
Типовое значение `64k` достаточно примерно для 25 контейнеров.
При возникновении ошибок подключения к Docker API или обработки ответов
модуль автоматически повторяет попытки через определенные интервалы времени.
Максимальное количество повторных попыток для получения информации
о конкретном контейнере ограничено двумя *дополнительными* попытками;
после этого модуль прекращает попытки для данного контейнера.
# https://angie.software/angie/docs/configuration/modules/http/http_empty_gif.md
# Empty GIF
Выдает однопиксельный прозрачный GIF.
## Пример конфигурации
```nginx
location = /_.gif {
empty_gif;
}
```
## Директивы
### empty_gif
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `empty_gif`; |
|------------------------------------------------------------------------------------------|----------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Разрешает в содержащем location выдавать однопиксельный прозрачный GIF.
# https://angie.software/angie/docs/configuration/modules/http/http_fastcgi.md
# FastCGI
Позволяет передавать запросы FastCGI-серверу.
## Пример конфигурации
```nginx
location / {
fastcgi_pass localhost:9000;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
fastcgi_param QUERY_STRING $query_string;
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;
}
```
## Директивы
### fastcgi_bind
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_bind` адрес [`transparent`] | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает локальный IP-адрес с необязательным портом, который будет использоваться в исходящих соединениях с FastCGI-сервером. В значении параметра допустимо использование переменных. Специальное значение `off` отменяет действие унаследованной с предыдущего уровня конфигурации директивы fastcgi_bind, позволяя системе самостоятельно выбирать локальный IP-адрес и порт.
Параметр `transparent` позволяет задать нелокальный IP-адрес, который будет использоваться в исходящих соединениях с FastCGI-сервером, например, реальный IP-адрес клиента:
```nginx
fastcgi_bind $remote_addr transparent;
```
Для работы параметра обычно требуется запустить рабочие процессы Angie с привилегиями [суперпользователя](https://angie.software//angie/docs/configuration/modules/core.md#user). В Linux это не требуется, так как если указан параметр transparent, то рабочие процессы наследуют capability CAP_NET_RAW из главного процесса.
#### NOTE
Необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с FastCGI-сервера.
### fastcgi_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_buffer_size` размер; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `fastcgi_buffer_size 4k|8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает размер буфера, в который будет читаться первая часть ответа, получаемого от FastCGI-сервера. В этой части ответа обычно находится небольшой заголовок ответа. По умолчанию размер одного буфера равен размеру страницы памяти. В зависимости от платформы это или 4K, или 8K, однако его можно сделать меньше.
### fastcgi_buffering
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_buffering` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `fastcgi_buffering on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает использовать буферизацию ответов FastCGI-сервера.
| `on` | Angie принимает ответ FastCGI-сервера как можно быстрее, сохраняя его в
буферы, заданные директивами [fastcgi_buffer_size](#fastcgi-buffer-size) и
[fastcgi_buffers](#fastcgi-buffers). Отправка клиенту при этом выполняется
параллельно: заполненные буферы передаются на отправку (никто их не
удерживает), но суммарно не более значения
[fastcgi_busy_buffers_size](#fastcgi-busy-buffers-size). Если буфер заполнен не полностью, то
на отправку он не передается, если только это не последние данные
ответа. Поэтому для моментальной передачи каждых нескольких байт режим
буферизированного чтения не подходит. Если ответ не вмещается целиком в
память, то его часть может быть записана на диск во [временный файл](#fastcgi-temp-path). Запись во временные файлы контролируется
директивами [fastcgi_max_temp_file_size](#fastcgi-max-temp-file-size) и
[fastcgi_temp_file_write_size](#fastcgi-temp-file-write-size). |
|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | Ответ передается клиенту сразу же по мере его поступления. Angie
работает в цикле «прочитал — отправил» и не ждет, пока буфер заполнится
целиком: например, прочитанные 10 байт из буфера 4К будут сразу
отправлены клиенту. При этом если весь ответ умещается в буфер, Angie
может прочитать его целиком. Максимальный размер данных, который Angie
может принять от сервера за один раз, задается директивой
[fastcgi_buffer_size](#fastcgi-buffer-size). При `off` не работает
[fastcgi_limit_rate](#fastcgi-limit-rate). |
Буферизация может быть также включена или выключена путем передачи значения "yes" или "no" в поле `X-Accel-Buffering` заголовка ответа. Эту возможность можно запретить с помощью директивы [fastcgi_ignore_headers](#fastcgi-ignore-headers).
### fastcgi_buffers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_buffers` число размер; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `fastcgi_buffers 8 4k | 8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число и размер буферов для одного соединения, в которые будет читаться ответ, получаемый от FastCGI-сервера.
По умолчанию размер одного буфера равен размеру страницы. В зависимости от платформы это или 4K, или 8K.
### fastcgi_busy_buffers_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_busy_buffers_size` размер; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `fastcgi_busy_buffers_size 8k | 16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
При включенной [буферизации](#fastcgi-buffering) ответов FastCGI-сервера, ограничивает суммарный размер буферов, которые могут быть заняты для отправки ответа клиенту, пока ответ еще не прочитан целиком. Оставшиеся буферы тем временем могут использоваться для чтения ответа и, при необходимости, буферизации части ответа во временный файл. По умолчанию размер ограничен двумя буферами, заданными директивами [fastcgi_buffer_size](#fastcgi-buffer-size) и [fastcgi_buffers](#fastcgi-buffers).
### fastcgi_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache` зона | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `fastcgi_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает зону разделяемой памяти, используемую для кэширования. Одна и та же зона может использоваться в нескольких местах. В значении параметра можно использовать переменные. Параметр `off` запрещает кэширование, унаследованное с предыдущего уровня конфигурации.
### fastcgi_cache_background_update
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_background_update` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| По умолчанию | `fastcgi_cache_background_update off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запустить фоновый подзапрос для обновления просроченного элемента кэша, в то время как клиенту возвращается устаревший кэшированный ответ. Использование устаревшего кэшированного ответа в момент его обновления должно быть [разрешено](#fastcgi-cache-use-stale-updating).
### fastcgi_cache_bypass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_bypass` строка ...; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает условия, при которых ответ не будет браться из кэша. Если значение хотя бы одного из строковых параметров непустое и не равно "0", то ответ не берется из кэша:
```nginx
fastcgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
fastcgi_cache_bypass $http_pragma $http_authorization;
```
Можно использовать совместно с директивой [fastcgi_no_cache](#fastcgi-no-cache).
### fastcgi_cache_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_key` строка; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает ключ для кэширования, например,
```nginx
fastcgi_cache_key localhost:9000$request_uri;
```
### fastcgi_cache_lock
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_lock` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `fastcgi_cache_lock off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если включено, одновременно только одному запросу будет позволено заполнить новый элемент кэша, идентифицируемый согласно директиве [fastcgi_cache_key](#fastcgi-cache-key), передав запрос на FastCGI-сервер. Остальные запросы этого же элемента будут либо ожидать появления ответа в кэше, либо освобождения блокировки этого элемента, в течение времени, заданного директивой [fastcgi_cache_lock_timeout](#fastcgi-cache-lock-timeout).
### fastcgi_cache_lock_age
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_lock_age` время; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `fastcgi_cache_lock_age 5s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если последний запрос, переданный на FastCGI-сервер для заполнения нового элемента кэша, не завершился за указанное время, на FastCGI-сервер может быть передан еще один запрос.
### fastcgi_cache_lock_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_lock_timeout` время; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `fastcgi_cache_lock_timeout 5s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут для [fastcgi_cache_lock](#fastcgi-cache-lock). По истечении указанного времени запрос будет передан на FastCGI-сервер, однако ответ не будет кэширован.
### fastcgi_cache_max_range_offset
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_max_range_offset` число; |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает смещение в байтах для запросов с указанием диапазона запрашиваемых байт (byte-range requests). Если диапазон находится за указанным смещением, range-запрос будет передан на FastCGI-сервер и ответ не будет кэширован.
### fastcgi_cache_methods
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_methods` `GET` | `HEAD` | `POST` ...; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------|
| По умолчанию | `fastcgi_cache_methods GET HEAD;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если метод запроса клиента указан в этой директиве, то ответ будет кэширован. Методы "GET" и "HEAD" всегда добавляются в список, но тем не менее рекомендуется перечислять их явно. См. также директиву [fastcgi_no_cache](#fastcgi-no-cache).
### fastcgi_cache_min_uses
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_min_uses` число; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `fastcgi_cache_min_uses 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число запросов, после которого ответ будет кэширован.
#### WARNING
Метаданные кэша хранятся в разделяемой памяти. Ручное удаление файлов кэша не
сбрасывает счетчики и может привести к непредсказуемому поведению. Для
полного сброса остановите сервер, удалите директорию кэша и запустите снова.
#### NOTE
Сторонние модули очистки кэша (например, [Cache Purge](https://angie.software//angie/docs/installation/external-modules/cache-purge.md#external-cache-purge)) удаляют только
файлы, но не сбрасывают счетчик fastcgi_cache_min_uses. Директива
предназначена для защиты кэша от загрязнения редкими запросами, и сброс
счетчика при очистке может негативно повлиять на производительность.
### fastcgi_cache_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_path` путь [`levels=`уровни] [`use_temp_path=``on` | `off`] `keys_zone=`имя:размер [`inactive=`время] [`max_size=`размер] [`min_free=`размер] [`manager_files=`число] [`manager_sleep=`время] [`manager_threshold=`время] [`loader_files=`число] [`loader_sleep=`время] [`loader_threshold=`время]; |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает путь и другие параметры кэша. Данные кэша хранятся в файлах. Ключом и именем файла в кэше является результат функции MD5 от проксированного URL.
Параметр `levels` задает уровни иерархии кэша: можно задать от 1 до 3 уровней, на каждом уровне допускаются значения 1 или 2. Например, при использовании
```nginx
fastcgi_cache_path /data/angie/cache levels=1:2 keys_zone=one:10m;
```
имена файлов в кэше будут такого вида:
```nginx
/data/angie/cache/c/29/b7f54b2df7773722d382f4809d65029c
```
Кэшируемый ответ сначала записывается во временный файл, а потом этот файл переименовывается. Временные файлы и кэш могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешевой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если кэш будет находиться на той же файловой системе, что и каталог с временными файлами.
Какой из каталогов будет использоваться для временных файлов определяется параметром `use_temp_path`.
| `on` | Если параметр не задан или установлен в значение "on", будет использоваться каталог, задаваемый директивой [fastcgi_temp_path](#fastcgi-temp-path) для данного location. |
|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | временные файлы будут располагаться непосредственно в каталоге кэша. |
Кроме того, все активные ключи и информация о данных хранятся в зоне разделяемой памяти, имя и размер которой задаются параметром `keys_zone`. Зоны размером в 1 мегабайт достаточно для хранения около 8 тысяч ключей. Метаданные кэша хранятся в разделяемой памяти.
Если к данным кэша не обращаются в течение времени, заданного параметром `inactive`, то данные удаляются, независимо от их свежести.
По умолчанию `inactive` равен 10 минутам.
Специальный процесс **менеджера кэша** следит за максимальным размером кэша, а также за минимальным объемом свободного места на файловой системе с кэшем, и удаляет наименее востребованные данные при превышении максимального размера кэша или недостаточном объеме свободного места. Удаление данных происходит итерациями.
| `max_size` | максимальное пороговое значение размера кэша |
|---------------------|--------------------------------------------------------------------------------------------------------|
| `min_free` | минимальное пороговое значение объема свободного места на файловой системе с кэшем |
| `manager_files` | максимальное количество удаляемых элементов кэша за одну итерацию
По умолчанию: `100` |
| `manager_threshold` | ограничивает время работы одной итерации
По умолчанию: `200` миллисекунд |
| `manager_sleep` | время, в течение которого выдерживается пауза между итерациями
По умолчанию: `50` миллисекунд |
Через минуту после старта Angie активируется специальный процесс **загрузчика кэша**, который загружает в зону кэша информацию о ранее кэшированных данных, хранящихся на файловой системе. Загрузка также происходит итерациями.
| `loader_files` | максимальное количество элементов кэша к загрузке в одну итерацию
По умолчанию: `100` |
|--------------------|--------------------------------------------------------------------------------------------------------|
| `loader_threshold` | ограничивает время работы одной итерации
По умолчанию: `200` миллисекунд |
| `loader_sleep` | время, в течение которого выдерживается пауза между итерациями
По умолчанию: `50` миллисекунд |
### fastcgi_cache_revalidate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_revalidate` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `fastcgi_cache_revalidate off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает ревалидацию просроченных элементов кэша при помощи условных запросов с полями заголовка `If-Modified-Since` и `If-None-Match` .
### fastcgi_cache_use_stale
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_use_stale` `error` | `timeout` | `invalid_header` | `updating` | `http_500` | `http_503` | `http_403` | `http_429` | `off` ...; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `fastcgi_cache_use_stale off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, в каких случаях можно использовать устаревший кэшированный ответ. Параметры директивы совпадают с параметрами директивы [fastcgi_next_upstream](#fastcgi-next-upstream).
| `error` | позволяет использовать устаревший кэшированный ответ при невозможности выбора FastCGI-сервера для обработки запроса. |
|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `updating` | дополнительный параметр, разрешает использовать устаревший кэшированный ответ, если на данный момент он уже обновляется. Это позволяет минимизировать число обращений к FastCGI-серверам при обновлении кэшированных данных. |
Использование устаревшего кэшированного ответа может также быть разрешено непосредственно в заголовке ответа на определенное количество секунд после того, как ответ устарел.
* Расширение [stale-while-revalidate](https://datatracker.ietf.org/doc/html/rfc5861#section-3) поля заголовка `Cache-Control` разрешает использовать устаревший кэшированный ответ, если на данный момент он уже обновляется.
* Расширение [stale-if-error](https://datatracker.ietf.org/doc/html/rfc5861#section-4) поля заголовка `Cache-Control` разрешает использовать устаревший кэшированный ответ в случае ошибки.
#### NOTE
Такой способ менее приоритетен, чем задание параметров директивы.
Чтобы минимизировать число обращений к FastCGI-серверам при заполнении нового элемента кэша, можно воспользоваться директивой [fastcgi_cache_lock](#fastcgi-cache-lock).
### fastcgi_cache_valid
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_valid` [код ...] время; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает время кэширования для разных кодов ответа. Например, директивы
```nginx
fastcgi_cache_valid 200 302 10m;
fastcgi_cache_valid 404 1m;
```
задают время кэширования 10 минут для ответов с кодами 200 и 302 и 1 минуту для ответов с кодом 404.
Если указано только время кэширования,
```nginx
fastcgi_cache_valid 5m;
```
то кэшируются только ответы 200, 301 и 302.
Кроме того, можно кэшировать любые ответы с помощью параметра `any`:
```nginx
fastcgi_cache_valid 200 302 10m;
fastcgi_cache_valid 301 1h;
fastcgi_cache_valid any 1m;
```
#### NOTE
Параметры кэширования могут также быть заданы непосредственно в заголовке ответа. Такой способ приоритетнее, чем задание времени кэширования с помощью директивы.
* Поле заголовка `X-Accel-Expires` задает время кэширования ответа в секундах. Значение 0 запрещает кэшировать ответ. Если значение начинается с префикса @, оно задает абсолютное время в секундах с начала эпохи, до которого ответ может быть кэширован.
* Если в заголовке нет поля `X-Accel-Expires`, параметры кэширования определяются по полям заголовка `Expires` или `Cache-Control`.
* Ответ, в заголовке которого есть поле `Set-Cookie`, не будет кэшироваться.
* Ответ, в заголовке которого есть поле `Vary` со специальным значением "\*", не будет кэшироваться. Ответ, в заголовке которого есть поле `Vary` с другим значением, будет кэширован с учетом соответствующих полей заголовка запроса.
Обработка одного или более из этих полей заголовка может быть отключена при помощи директивы [fastcgi_ignore_headers](#fastcgi-ignore-headers).
### fastcgi_catch_stderr
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_catch_stderr` строка; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает строку для поиска в потоке ошибок ответа, полученного от FastCGI-сервера. Если строка найдена, то считается, что FastCGI-сервер вернул [неверный](#fastcgi-next-upstream) ответ. Это позволяет обрабатывать ошибки приложений в Angie, например:
```nginx
location /php/ {
fastcgi_pass backend:9000;
...
fastcgi_catch_stderr "PHP Fatal error";
fastcgi_next_upstream error timeout invalid_header;
}
```
### fastcgi_connect_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_connect_timeout` время; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `fastcgi_connect_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут для установления соединения с FastCGI-сервером. Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.
### fastcgi_connection_drop
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_connection_drop` время | `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| По умолчанию | `fastcgi_connection_drop off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Настраивает завершение всех соединений с проксируемым сервером,
если он был удален из группы или помечен как постоянно недоступный
в результате процесса [reresolve](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve)
или [команды API](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods) `DELETE`.
Соединение завершается, когда обрабатывается следующее событие чтения или записи
для клиента или проксируемого сервера.
Установка времени включает [таймаут](https://angie.software//angie/docs/configuration/configfile.md#syntax) до завершения соединения;
при выборе значения `on` соединения завершаются немедленно.
### fastcgi_force_ranges
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_force_ranges` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `fastcgi_force_ranges off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Включает поддержку диапазонов запрашиваемых байт (byte-range) для кэшированных и некэшированных ответов FastCGI-сервера вне зависимости от наличия поля `Accept-Ranges` в заголовках этих ответов.
### fastcgi_hide_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_hide_header` поле; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
По умолчанию Angie не передает клиенту поля заголовка `Status` и `X-Accel-...` из ответа FastCGI-сервера. Директива fastcgi_hide_header задает дополнительные поля, которые не будут передаваться. Если же передачу полей нужно разрешить, можно воспользоваться директивой [fastcgi_pass_header](#fastcgi-pass-header).
### fastcgi_ignore_client_abort
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_ignore_client_abort` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| По умолчанию | `fastcgi_ignore_client_abort off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, закрывать ли соединение с FastCGI-сервером в случае, если клиент закрыл соединение, не дождавшись ответа.
### fastcgi_ignore_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_ignore_headers` поле; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Запрещает обработку некоторых полей заголовка из ответа FastCGI-сервера. В директиве можно указать поля `X-Accel-Redirect`, `X-Accel-Expires`, `X-Accel-Limit-Rate`, `X-Accel-Buffering`, `X-Accel-Charset`, `Expires`, `Cache-Control`, `Set-Cookie` и `Vary`.
Если не запрещено, обработка этих полей заголовка заключается в следующем:
* `X-Accel-Expires`, `Expires`, `Cache-Control`, `Set-Cookie` и `Vary` задают [параметры кэширования](#fastcgi-cache-valid) ответа;
* `X-Accel-Redirect` производит [внутреннее перенаправление](https://angie.software//angie/docs/configuration/modules/http/index.md#internal) на указанный URI;
* `X-Accel-Limit-Rate` задает [ограничение скорости](https://angie.software//angie/docs/configuration/modules/http/index.md#limit-rate) передачи ответа клиенту;
* `X-Accel-Buffering` включает или выключает [буферизацию](#fastcgi-buffering) ответа;
* `X-Accel-Charset` задает желаемую [кодировку](https://angie.software//angie/docs/configuration/modules/http/http_charset.md#id3) ответа.
### fastcgi_index
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_index` имя; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает имя файла, который при создании переменной [$fastcgi_script_name](#v-fastcgi-script-name) будет добавляться после URI, если URI заканчивается косой чертой. Например, при таких настройках
```nginx
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
```
и запросе `/page.php` параметр SCRIPT_FILENAME будет равен `/home/www/scripts/php/page.php`,
а при запросе `/` - `/home/www/scripts/php/index.php`.
### fastcgi_intercept_errors
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_intercept_errors` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `fastcgi_intercept_errors off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, передавать ли клиенту ответы FastCGI-сервера с кодом больше либо равным 300, или же перехватывать их и перенаправлять на обработку Angie с помощью директивы [error_page](https://angie.software//angie/docs/configuration/modules/http/index.md#error-page).
### fastcgi_keep_conn
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_keep_conn` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `fastcgi_keep_conn off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
По умолчанию FastCGI-сервер будет закрывать соединение сразу же после отправки ответа. При установке значения `on` Angie указывает FastCGI-серверу оставлять соединения открытыми. Это в частности требуется для функционирования [постоянных соединений](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive) с FastCGI-серверами.
### fastcgi_limit_rate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_limit_rate` скорость; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `fastcgi_limit_rate 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает скорость чтения ответа от проксируемого сервера.
Скорость задается в байтах в секунду; можно использовать переменные.
| `0` | отключает ограничение скорости |
|-------|----------------------------------|
#### NOTE
Ограничение устанавливается на запрос, поэтому, если Angie одновременно откроет два соединения к FastCGI-серверу, суммарная скорость будет вдвое выше заданного ограничения. Ограничение работает только в случае, если включена [буферизация](#fastcgi-buffering) ответов FastCGI-сервера.
### fastcgi_max_temp_file_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_max_temp_file_size` размер; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `fastcgi_max_temp_file_size 1024m;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если включена [буферизация](#fastcgi-buffering) ответов FastCGI-сервера, и ответ не вмещается целиком в буферы, заданные директивами [fastcgi_buffer_size](#fastcgi-buffer-size) и [fastcgi_buffers](#fastcgi-buffers), часть ответа может быть записана во временный файл. Эта директива задает максимальный размер временного файла. Размер данных, сбрасываемых во временный файл за один раз, задается директивой [fastcgi_temp_file_write_size](#fastcgi-temp-file-write-size).
| `0` | отключает возможность буферизации ответов во временные файлы |
|-------|----------------------------------------------------------------|
#### NOTE
Данное ограничение не распространяется на ответы, которые будут [кэшированы](#fastcgi-cache) или сохранены [на диске](#fastcgi-store).
### fastcgi_next_upstream
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_next_upstream` `error` | `timeout` | `invalid_header` | `http_500` | `http_503` | `http_403` | `http_404` | `http_429` | `non_idempotent` | `off` ...; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `fastcgi_next_upstream error timeout;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, в каких случаях запрос будет передан следующему серверу:
| `error` | произошла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `timeout` | произошел таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
| `invalid_header` | сервер вернул пустой или неверный ответ; |
| `http_500` | сервер вернул ответ с кодом 500; |
| `http_503` | сервер вернул ответ с кодом 503; |
| `http_403` | сервер вернул ответ с кодом 403; |
| `http_404` | сервер вернул ответ с кодом 404; |
| `http_429` | сервер вернул ответ с кодом 429; |
| `non_idempotent` | обычно запросы с [неидемпотентным](https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2) методом (POST, LOCK, PATCH) не передаются на другой сервер, если запрос серверу группы уже был отправлен; включение параметра явно разрешает повторять подобные запросы; |
| `off` | запрещает передачу запроса следующему серверу. |
#### NOTE
Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту еще ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа, то исправить это уже невозможно.
Директива также определяет, что считается [неудачной попыткой](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) работы с сервером.
| `error`
`timeout`
`invalid_header` | всегда считаются неудачными попытками, даже если они не указаны в директиве |
|--------------------------------------------------------|-------------------------------------------------------------------------------|
| `http_500`
`http_503`
`http_429` | считаются неудачными попытками, только если они указаны в директиве |
| `http_403`
`http_404` | никогда не считаются неудачными попытками |
Передача запроса следующему серверу может быть ограничена по [количеству попыток](#fastcgi-next-upstream-tries) и по [времени](#fastcgi-next-upstream-timeout).
### fastcgi_next_upstream_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_next_upstream_timeout` время; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `fastcgi_next_upstream_timeout 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает время, в течение которого возможна передача запроса [следующему серверу](#fastcgi-next-upstream).
| `0` | отключает это ограничение |
|-------|-----------------------------|
### fastcgi_next_upstream_tries
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_next_upstream_tries` число; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `fastcgi_next_upstream_tries 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает число допустимых попыток для передачи запроса [следующему серверу](#fastcgi-next-upstream).
| `0` | отключает это ограничение |
|-------|-----------------------------|
### fastcgi_no_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_no_cache` строка ...; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает условия, при которых ответ не будет сохраняться в кэш. Если значение хотя бы одного из строковых параметров непустое и не равно "0", то ответ не будет сохранен:
```nginx
fastcgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
fastcgi_no_cache $http_pragma $http_authorization;
```
Можно использовать совместно с директивой [fastcgi_cache_bypass](#fastcgi-cache-bypass).
### fastcgi_param
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_param` параметр значение [`if_not_empty`]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает параметр, который будет передаваться FastCGI-серверу. В качестве значения можно использовать текст, переменные и их комбинации. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы fastcgi_param.
#### NOTE
В стандартных файлах `fastcgi.conf` и `fastcgi_params`, поставляемых
с Angie, параметр `REQUEST_METHOD` задаётся как
`$upstream_request_method`. Это позволяет при конвертации
`HEAD` в `GET` при кэшировании использовать корректный метод
для запроса к upstream.
Ниже приведен пример минимально необходимых параметров для PHP:
```nginx
fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
fastcgi_param QUERY_STRING $query_string;
```
Параметр SCRIPT_FILENAME используется в PHP для определения имени скрипта, а в параметре QUERY_STRING передаются параметры запроса.
Если скрипты обрабатывают запросы POST, то нужны еще три параметра:
```nginx
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;
```
Если PHP был собран с параметром конфигурации `--enable-force-cgi-redirect`, то нужно передавать параметр REDIRECT_STATUS со значением "200":
```nginx
fastcgi_param REDIRECT_STATUS 200;
```
Если директива указана с `if_not_empty`, такой параметр с пустым значением передаваться на сервер не будет:
```nginx
fastcgi_param HTTPS $https if_not_empty;
```
### fastcgi_pass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_pass` адрес; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location, if в location |
Задает адрес FastCGI-сервера. Адрес может быть указан в виде доменного имени или IP-адреса, и порта:
```nginx
fastcgi_pass localhost:9000;
```
или в виде пути UNIX-сокета:
```nginx
fastcgi_pass unix:/tmp/fastcgi.socket;
```
Если доменному имени соответствует несколько адресов, то все они будут использоваться по очереди (round-robin). И, кроме того, адрес может быть [группой серверов](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).
В значении параметра можно использовать переменные. В этом случае, если адрес указан в виде доменного имени, имя ищется среди описанных [групп серверов](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) и если не найдено, то определяется с помощью [resolver](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver)'а.
#### NOTE
Если `fastcgi_pass` стоит в `location` с косой чертой в конце префикса
(например, `location /name/`),
и при этом в директиве [auto_redirect](https://angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) указано `default`,
запросы без косой черты в конце будут перенаправляться (`/name -> /name/`).
### fastcgi_pass_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_pass_header` поле; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает передавать от FastCGI-сервера клиенту [запрещенные для передачи](#fastcgi-hide-header) поля заголовка.
### fastcgi_pass_request_body
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_pass_request_body` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запретить передачу исходного тела запроса на FastCGI-сервер. См. также директиву [fastcgi_pass_request_headers](#fastcgi-pass-request-headers).
### fastcgi_pass_request_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_pass_request_headers` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запретить передачу полей заголовка исходного запроса на FastCGI-сервер. См. также директиву [fastcgi_pass_request_body](#fastcgi-pass-request-body).
### fastcgi_read_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_read_timeout` время; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `fastcgi_read_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при чтении ответа FastCGI-сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени FastCGI-сервер ничего не передаст, соединение закрывается.
### fastcgi_request_buffering
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_request_buffering` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | `fastcgi_request_buffering on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает использовать буферизацию тела запроса клиента.
| `on` | тело запроса полностью [читается](https://angie.software//angie/docs/configuration/modules/http/index.md#client-body-buffer-size) от клиента перед отправкой запроса на FastCGI-сервер. |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | тело запроса отправляется на FastCGI-сервер сразу же по мере его поступления. В этом случае запрос не может быть передан [следующему серверу](#fastcgi-next-upstream), если Angie уже начал отправку тела запроса. |
### fastcgi_send_lowat
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_send_lowat` размер; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `fastcgi_send_lowat 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
При установке директивы в ненулевое значение Angie будет пытаться
минимизировать число операций отправки на исходящих соединениях с
FastCGI-сервером либо при помощи флага `NOTE_LOWAT` метода [kqueue](https://angie.software//angie/docs/configuration/processing.md#kqueue), либо при помощи параметра сокета `SO_SNDLOWAT`, с указанным
размером.
#### NOTE
Эта директива игнорируется на Linux, Solaris и Windows.
### fastcgi_send_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_send_timeout` время; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `fastcgi_send_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при передаче запроса FastCGI-серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени FastCGI-сервер не примет новых данных, соединение закрывается.
### fastcgi_socket_keepalive
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_socket_keepalive` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `fastcgi_socket_keepalive off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Конфигурирует поведение "TCP keepalive" для исходящих соединений к FastCGI-серверу.
| `""` | По умолчанию для сокета действуют настройки операционной системы. |
|--------|---------------------------------------------------------------------|
| `on` | для сокета включается параметр SO_KEEPALIVE |
### fastcgi_split_path_info
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_split_path_info` regex; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Задает регулярное выражение, выделяющее значение для переменной [$fastcgi_path_info](#v-fastcgi-path-info). Регулярное выражение должно иметь две группы захвата, из которых первая становится значением переменной [$fastcgi_script_name](#v-fastcgi-script-name), а вторая — значением переменной [$fastcgi_path_info](#v-fastcgi-path-info). Например, при таких настройках
```default
location ~ ^(.+\.php)(.*)$ {
fastcgi_split_path_info ^(.+\.php)(.*)$;
fastcgi_param SCRIPT_FILENAME /path/to/php$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;
```
и запросе `/show.php/article/0001` параметр SCRIPT_FILENAME будет равен `/path/to/php/show.php`,
а параметр PATH_INFO - `/article/0001`.
### fastcgi_store
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_store` `on` | `off` | строка; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `fastcgi_store off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает сохранение на диск файлов.
| `on` | сохраняет файлы в соответствии с путями, указанными в директивах [alias](https://angie.software//angie/docs/configuration/modules/http/index.md#alias) или [root](https://angie.software//angie/docs/configuration/modules/http/index.md#root) |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | запрещает сохранение файлов |
Кроме того, имя файла можно задать явно с помощью строки с переменными:
```nginx
fastcgi_store /data/www$original_uri;
```
Время изменения файлов выставляется согласно полученному полю `Last-Modified` в заголовке ответа. Ответ сначала записывается во временный файл, а потом этот файл переименовывается. Временный файл и постоянное место хранения ответа могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешевой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой системе, что и каталог с временными файлами, задаваемый директивой [fastcgi_temp_path](#fastcgi-temp-path) для данного location.
Директиву можно использовать для создания локальных копий статических неизменяемых файлов, например:
```nginx
location /images/ {
root /data/www;
error_page 404 = /fetch$uri;
}
location /fetch/ {
internal;
fastcgi_pass backend:9000;
...
fastcgi_store on;
fastcgi_store_access user:rw group:rw all:r;
fastcgi_temp_path /data/temp;
alias /data/www/;
}
```
### fastcgi_store_access
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_store_access` пользователи:права ...; |
|------------------------------------------------------------------------------------------|--------------------------------------------------|
| По умолчанию | `fastcgi_store_access user:rw;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает права доступа для создаваемых файлов и каталогов, например,
```nginx
fastcgi_store_access user:rw group:rw all:r;
```
Если заданы какие-либо права для group или all, то права для user указывать необязательно:
```nginx
fastcgi_store_access group:rw all:r;
```
### fastcgi_temp_file_write_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_temp_file_write_size` размер; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `fastcgi_temp_file_write_size 8k|16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает размер данных, сбрасываемых во временный файл за один раз, при включенной буферизации ответов FastCGI-сервера во временные файлы. По умолчанию размер ограничен двумя буферами, заданными директивами [fastcgi_buffer_size](#fastcgi-buffer-size) и [fastcgi_buffers](#fastcgi-buffers). Максимальный размер временного файла задается директивой [fastcgi_max_temp_file_size](#fastcgi-max-temp-file-size).
### fastcgi_temp_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_temp_path` путь [уровень1 [уровень2 [уровень3]]]\`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `fastcgi_temp_path fastcgi_temp;`
(путь зависит от [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-fastcgi-temp-path`) |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает имя каталога для хранения временных файлов с данными, полученными от FastCGI-серверов. В каталоге может использоваться иерархия подкаталогов до трех уровней. Например, при такой конфигурации
```nginx
fastcgi_temp_path /spool/angie/fastcgi_temp 1 2;
```
временный файл будет следующего вида:
```nginx
/spool/angie/fastcgi_temp/7/45/00000123457
```
См. также параметр use_temp_path директивы [fastcgi_cache_path](#fastcgi-cache-path).
## Параметры, передаваемые FastCGI-серверу
Поля заголовка HTTP-запроса передаются FastCGI-серверу в виде параметров. В приложениях и скриптах, запущенных в виде FastCGI-сервера, эти параметры обычно доступны в виде переменных среды. Например, поле заголовка `User-Agent` передается как параметр HTTP_USER_AGENT. Кроме полей заголовка HTTP-запроса можно передавать произвольные параметры с помощью директивы [fastcgi_param](#fastcgi-param).
## Встроенные переменные
В модуле http_fastcgi есть встроенные переменные, которые можно использовать для формирования параметров с помощью директивы [fastcgi_param](#fastcgi-param):
### `$fastcgi_script_name`
URI запроса или же, если URI заканчивается косой чертой, то URI запроса, дополненное именем индексного файла, задаваемого директивой [fastcgi_index](#fastcgi-index). Эту переменную можно использовать для задания параметров SCRIPT_FILENAME и PATH_TRANSLATED, используемых, в частности, для определения имени скрипта в PHP. Например, для запроса `/info/` и при использовании директив
```nginx
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
```
параметр SCRIPT_FILENAME будет равен `/home/www/scripts/php/info/index.php`.
При использовании директивы [fastcgi_split_path_info](#fastcgi-split-path-info) переменная $fastcgi_script_name равна значению первой группы захвата, задаваемой этой директивой.
### `$fastcgi_path_info`
значение второй группы захвата, задаваемой директивой [fastcgi_split_path_info](#fastcgi-split-path-info). Эту переменную можно использовать для задания параметра PATH_INFO.
# https://angie.software/angie/docs/configuration/modules/http/http_flv.md
# FLV
Обеспечивает серверную поддержку псевдо-стриминга для файлов Flash Video (FLV).
Он специальным образом обрабатывает запросы с аргументом `start` в строке запроса, посылая в ответ содержимое файла с запрошенного смещения в байтах, добавив перед ним FLV-заголовок.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_flv_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
## Пример конфигурации
```nginx
location ~ \.flv$ {
flv;
}
```
## Директивы
### flv
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `flv`; |
|------------------------------------------------------------------------------------------|----------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Включает в содержащем location обработку этим модулем.
# https://angie.software/angie/docs/configuration/modules/http/http_geo.md
# Geo
Создает переменные, значения которых зависят от IP-адреса клиента.
## Пример конфигурации
```nginx
geo $geo {
default 0;
127.0.0.1 2;
192.168.1.0/24 1;
10.1.0.0/16 1;
::1 2;
2001:0db8::/32 1;
}
```
## Директивы
### geo
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `geo` [$адрес] $переменная { ... } |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Описывает для указанной переменной зависимость значения от IP-адреса клиента. По умолчанию адрес берется из переменной [$remote_addr](https://angie.software//angie/docs/configuration/modules/http/index.md#v-remote-addr), но его также можно получить из другой переменной, например:
```nginx
geo $arg_remote_addr $geo {
...;
}
```
#### NOTE
Поскольку переменные вычисляются только в момент использования, само по себе наличие даже большого числа объявлений переменных `geo` не влечет за собой никаких дополнительных расходов на обработку запросов.
Если значение переменной не представляет собой правильный IP-адрес, то используется адрес "255.255.255.255".
Адреса задаются либо префиксами в формате CIDR (включая одиночные адреса), либо в виде диапазонов.
Также поддерживаются следующие специальные параметры:
| `delete` | удаляет описанную сеть |
|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `default` | значение переменной, если адрес клиента не соответствует ни одному из заданных адресов. При задании адресов в формате CIDR вместо default можно использовать "0.0.0.0/0" и "::/0". Если параметр default не указан, значением по умолчанию будет пустая строка. |
| `include` | включает файл с адресами и значениями. Включений может быть несколько. |
| `proxy` | задает доверенные адреса, при запросе с которых будет использоваться адрес в переданном поле заголовка запроса `X-Forwarded-For`. В отличие от обычных адресов, доверенные адреса проверяются последовательно. |
| `proxy_recursive` | включает рекурсивный поиск адреса. При выключенном рекурсивном поиске вместо исходного адреса клиента, совпадающего с одним из доверенных адресов, будет использоваться последний адрес, переданный в `X-Forwarded-For`. При включенном рекурсивном поиске вместо исходного адреса клиента, совпадающего с одним из доверенных адресов, будет использоваться последний не доверенный адрес, переданный в `X-Forwarded-For`. |
| `ranges` | указывает, что адреса задаются в виде диапазонов. Этот параметр должен быть первым. Для ускорения загрузки гео-базы нужно располагать адреса в порядке возрастания. |
| `volatile` | указывает, что переменная не кэшируется. |
Пример:
```nginx
geo $country {
default ZZ;
include conf/geo.conf;
delete 127.0.0.0/16;
proxy 192.168.100.0/24;
proxy 2001:0db8::/32;
127.0.0.0/24 US;
127.0.0.1/32 RU;
10.1.0.0/16 RU;
192.168.1.0/24 UK;
}
```
В файле `conf/geo.conf` могут быть такие строки:
```console
10.2.0.0/16 RU;
192.168.2.0/24 RU;
```
В качестве значения выбирается максимальное совпадение, например, для адреса `127.0.0.1` будет выбрано значение `RU`, а не `US`.
Пример описания диапазонов:
```nginx
geo $country {
ranges;
default ZZ;
127.0.0.0-127.0.0.0 US;
127.0.0.1-127.0.0.1 RU;
127.0.0.2-127.0.0.255 US;
10.1.0.0-10.1.255.255 RU;
192.168.1.0-192.168.1.255 UK;
}
```
# https://angie.software/angie/docs/configuration/modules/http/http_geoip.md
# GeoIP
Создает переменные, значения которых зависят от IP-адреса клиента, используя
готовые базы данных [MaxMind](http://www.maxmind.com/)
или их аналоги.
При использовании баз данных с поддержкой IPv6
IPv4-адреса ищутся отображенными на IPv6.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_geoip_module`.
#### NOTE
Для этого модуля нужна база данных MaxMind [MaxMind GeoIP](https://www.maxmind.com/en/geoip-databases)
или ее аналог,
например [MaxMind GeoLite2](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data)
или [ЦМУ ССОП](https://geoip.noc.gov.ru/).
## Пример конфигурации
```nginx
http {
geoip_country GeoIP.dat;
geoip_city GeoLiteCity.dat;
geoip_proxy 192.168.100.0/24;
geoip_proxy 2001:0db8::/32;
geoip_proxy_recursive on;
...
```
## Директивы
### geoip_country
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `geoip_country` файл; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает базу данных для определения страны в зависимости от значения IP-адреса клиента. При использовании этой базы данных доступны следующие переменные:
| `$geoip_country_code` | двухбуквенный код страны, например, "RU", "US". |
|-------------------------|-------------------------------------------------------------------|
| `$geoip_country_code3` | трехбуквенный код страны, например, "RUS", "USA". |
| `$geoip_country_name` | название страны, например, "Russian Federation", "United States". |
### geoip_city
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `geoip_city` файл; |
|------------------------------------------------------------------------------------------|----------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает базу данных для определения страны, региона и города в зависимости от значения IP-адреса клиента. При использовании этой базы данных доступны следующие переменные:
| `$geoip_city_continent_code` | двухбуквенный код континента, например, "EU", "NA". |
|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `$geoip_city_country_code` | двухбуквенный код страны, например, "RU", "US". |
| `$geoip_city_country_code3` | трехбуквенный код страны, например, "RUS", "USA". |
| `$geoip_city_country_name` | название страны, например, "Russian Federation", "United States". |
| `$geoip_dma_code` | DMA-код региона в США (также известный как "код агломерации"), согласно [геотаргетингу](https://developers.google.com/adwords/api/docs/appendix/cities-DMAregions) Google AdWords API. |
| `$geoip_latitude` | широта. |
| `$geoip_longitude` | долгота. |
| `$geoip_region` | двухсимвольный код региона страны (область, край, штат, провинция, федеральная земля и тому подобное), например, "48", "DC". |
| `$geoip_region_name` | название региона страны (область, край, штат, провинция, федеральная земля и тому подобное), например, "Moscow City", "District of Columbia". |
| `$geoip_city` | название города, например, "Moscow", "Washington". |
| `$geoip_postal_code` | почтовый индекс. |
### geoip_org
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `geoip_org` файл; |
|------------------------------------------------------------------------------------------|---------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает базу данных для определения названия организации в зависимости от значения IP-адреса клиента. При использовании этой базы данных доступна следующая переменная:
| `$geoip_org` | название организации, например, "The University of Melbourne". |
|----------------|------------------------------------------------------------------|
### geoip_proxy
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `geoip_proxy` файл; |
|------------------------------------------------------------------------------------------|-----------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает доверенные адреса, при запросе с которых будет использоваться адрес в переданном поле заголовка запроса `X-Forwarded-For`.
### geoip_proxy_recursive
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `geoip_proxy_recursive` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `geoip_proxy_recursive off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
При выключенном рекурсивном поиске вместо исходного адреса клиента, совпадающего с одним из доверенных адресов, будет использоваться последний адрес, переданный в `X-Forwarded-For`. При включенном рекурсивном поиске вместо исходного адреса клиента, совпадающего с одним из доверенных адресов, будет использоваться последний не доверенный адрес, переданный в `X-Forwarded-For`.
# https://angie.software/angie/docs/configuration/modules/http/http_grpc.md
# gRPC
Позволяет передавать запросы gRPC-серверу.
#### NOTE
Для работы этого модуля необходим модуль [HTTP2](https://angie.software//angie/docs/configuration/modules/http/http_v2.md#http-v2).
## Пример конфигурации
```nginx
server {
listen 9000;
http2 on;
location / {
grpc_pass 127.0.0.1:9000;
}
}
```
## Директивы
### grpc_bind
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_bind` адрес [`transparent`] | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает локальный IP-адрес с необязательным портом, который будет использоваться в исходящих соединениях с gRPC-сервером. В значении параметра допустимо использование переменных. Специальное значение `off` отменяет действие унаследованной с предыдущего уровня конфигурации директивы grpc_bind, позволяя системе самостоятельно выбирать локальный IP-адрес и порт.
Параметр `transparent` позволяет задать нелокальный IP-aдрес, который будет использоваться в исходящих соединениях с gRPC-сервером, например, реальный IP-адрес клиента:
```nginx
grpc_bind $remote_addr transparent;
```
Для работы параметра обычно требуется запустить рабочие процессы Angie с привилегиями [суперпользователя](https://angie.software//angie/docs/configuration/modules/core.md#user). В Linux это не требуется, так как если указан параметр transparent, то рабочие процессы наследуют capability CAP_NET_RAW из главного процесса.
#### NOTE
Необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с gRPC-сервера.
### grpc_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_buffer_size` размер; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `grpc_buffer_size 4k|8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает размер буфера, в который будет читаться первая часть ответа, получаемого от gRPC-сервера. Ответ синхронно передается клиенту сразу же по мере его поступления.
### grpc_connect_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_connect_timeout` время; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `grpc_connect_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут для установления соединения с gRPC-сервером. Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.
### grpc_connection_drop
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_connection_drop` время | `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| По умолчанию | `grpc_connection_drop off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Настраивает завершение всех соединений с проксируемым сервером,
если он был удален из группы или помечен как постоянно недоступный
в результате процесса [reresolve](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve)
или [команды API](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods) `DELETE`.
Соединение завершается, когда обрабатывается следующее событие чтения или записи
для клиента или проксируемого сервера.
Установка времени включает [таймаут](https://angie.software//angie/docs/configuration/configfile.md#syntax) до завершения соединения;
при выборе значения `on` соединения завершаются немедленно.
### grpc_hide_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_hide_header` поле; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
По умолчанию Angie не передает клиенту поля заголовка `Date`, `Server` и `X-Accel-...` из ответа gRPC-сервера. Директива `grpc_hide_header` задает дополнительные поля, которые не будут передаваться. Если же передачу полей нужно разрешить, можно воспользоваться директивой [grpc_pass_header](#grpc-pass-header).
### grpc_ignore_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ignore_headers` поле ...; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Запрещает обработку некоторых полей заголовка из ответа gRPC-сервера. В директиве можно указать поля `X-Accel-Redirect` и `X-Accel-Charset`.
Если не запрещено, обработка этих полей заголовка заключается в следующем:
* `X-Accel-Redirect` производит [внутреннее перенаправление](https://angie.software//angie/docs/configuration/modules/http/index.md#internal) на указанный URI;
* `X-Accel-Charset` задает желаемую [кодировку](https://angie.software//angie/docs/configuration/modules/http/http_charset.md#id3) ответа.
### grpc_intercept_errors
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_intercept_errors` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `grpc_intercept_errors off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, передавать ли клиенту ответы gRPC-сервера с кодом больше либо равным 300, или же перехватывать их и перенаправлять на обработку Angie с помощью директивы [error_page](https://angie.software//angie/docs/configuration/modules/http/index.md#error-page).
### grpc_next_upstream
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_next_upstream` `error` | `timeout` | `invalid_header` | `http_500` | `http_502` | `http_503` | `http_504` | `http_403` | `http_404` | `http_429` | `non_idempotent` | `off` ...; |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `grpc_next_upstream error timeout;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, в каких случаях запрос будет передан следующему в группе [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) серверу:
| `error` | произошла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `timeout` | произошел таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
| `invalid_header` | сервер вернул пустой или неверный ответ; |
| `http_500` | сервер вернул ответ с кодом 500; |
| `http_502` | сервер вернул ответ с кодом 502; |
| `http_503` | сервер вернул ответ с кодом 503; |
| `http_504` | сервер вернул ответ с кодом 504; |
| `http_403` | сервер вернул ответ с кодом 403; |
| `http_404` | сервер вернул ответ с кодом 404; |
| `http_429` | сервер вернул ответ с кодом 429; |
| `non_idempotent` | обычно запросы с [неидемпотентным](https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2) методом (POST, LOCK, PATCH) не передаются на другой сервер, если запрос серверу группы уже был отправлен; включение параметра явно разрешает повторять подобные запросы; |
| `off` | запрещает передачу запроса следующему серверу. |
#### NOTE
Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту еще ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа клиенту, то действие директивы на такой запрос не распространяется.
Директива также определяет, что считается [неудачной попыткой](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) работы с сервером.
| `error`, `timeout`, `invalid_header` | всегда считаются неудачными попытками, даже если они не указаны в директиве |
|------------------------------------------------------------|-------------------------------------------------------------------------------|
| `http_500`, `http_502`, `http_503`, `http_504`, `http_429` | считаются неудачными попытками, только если они указаны в директиве |
| `http_403`, `http_404` | никогда не считаются неудачными попытками |
Передача запроса следующему серверу может быть ограничена по [количеству попыток](#grpc-next-upstream-tries) и по [времени](#grpc-next-upstream-timeout).
### grpc_next_upstream_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_next_upstream_timeout` время; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `grpc_next_upstream_timeout 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает время, в течение которого возможна передача запроса [следующему](#grpc-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### grpc_next_upstream_tries
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_next_upstream_tries` число; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `grpc_next_upstream_tries 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает число допустимых попыток для передачи запроса [следующему](#grpc-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### grpc_pass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_pass` адрес; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location, if в location |
Задает адрес gRPC-сервера. Адрес может быть указан в виде доменного имени или IP-адреса, и порта:
```nginx
grpc_pass localhost:9000;
```
или в виде пути UNIX-сокета:
```nginx
grpc_pass unix:/tmp/grpc.socket;
```
Также может использоваться схема `grpc://`:
```nginx
grpc_pass grpc://127.0.0.1:9000;
```
Для использования gRPC по SSL необходимо использовать схему `grpcs://`:
```nginx
grpc_pass grpcs://127.0.0.1:443;
```
Если доменному имени соответствует несколько адресов, то все они будут использоваться по очереди (round-robin). Кроме того, в качестве адреса можно указать [группу серверов](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).
В значении параметра можно использовать переменные. В этом случае, если адрес указан в виде доменного имени, имя ищется среди описанных групп серверов и если не найдено, то определяется с помощью [resolver](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver)'а.
#### NOTE
Если `grpc_pass` стоит в `location` с косой чертой в конце префикса
(например, `location /name/`),
и при этом в директиве [auto_redirect](https://angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) указано `default`,
запросы без косой черты в конце будут перенаправляться (`/name -> /name/`).
### grpc_pass_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_pass_header` поле; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает передавать от gRPC-сервера клиенту [запрещенные для передачи](#grpc-hide-header) поля заголовка.
### grpc_read_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_read_timeout` время; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `grpc_read_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при чтении ответа gRPC-сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени gRPC-сервер ничего не передаст, соединение закрывается.
### grpc_send_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_send_timeout` время; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `grpc_send_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при передаче запроса gRPC-серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени gRPC-сервер не примет новых данных, соединение закрывается.
### grpc_set_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_set_header` поле значение; |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| По умолчанию | `grpc_set_header Content-Length $content_length;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет переопределять или добавлять поля заголовка запроса, [передаваемые](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass-request-headers) проксируемому серверу. В качестве значения можно использовать текст, переменные и их комбинации. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы grpc_set_header.
Если значение поля заголовка — пустая строка, то поле вообще не будет передаваться gRPC-серверу:
```nginx
grpc_set_header Accept-Encoding "";
```
### grpc_socket_keepalive
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_socket_keepalive` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `grpc_socket_keepalive off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Конфигурирует поведение "TCP keepalive" для исходящих соединений к проксируемому серверу.
| `""` | По умолчанию для сокета действуют настройки операционной системы. |
|--------|---------------------------------------------------------------------|
| `on` | для сокета включается параметр SO_KEEPALIVE |
### grpc_ssl_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_certificate` файл; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с сертификатом в формате PEM для аутентификации на gRPC SSL-сервере. В имени файла можно использовать переменные.
### grpc_ssl_certificate_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_certificate_cache` `off`;
`grpc_ssl_certificate_cache` `max=`N [`inactive=`time] [`valid=`time]; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| Значение по умолчанию | `grpc_ssl_certificate_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет кэш для хранения [SSL-сертификатов](#grpc-ssl-certificate) и [секретных ключей](#grpc-ssl-certificate-key), заданных через переменные.
Директива поддерживает следующие параметры:
- `max` — устанавливает максимальное количество элементов в кэше. При переполнении кэша
удаляются наименее недавно использованные (LRU) элементы.
- `inactive` — определяет время, после которого элемент будет удален, если
к нему не было обращений. Значение по умолчанию — 10 секунд.
- `valid` — определяет время, в течение которого элемент кэша считается
действительным и может использоваться повторно. Значение по умолчанию — 60 секунд. По истечении этого времени
сертификаты перезагружаются или проходят повторную проверку.
- `off` — отключает кэш.
Пример:
```nginx
grpc_ssl_certificate $grpc_ssl_server_name.crt;
grpc_ssl_certificate_key $grpc_ssl_server_name.key;
grpc_ssl_certificate_cache max=1000 inactive=20s valid=1m;
```
### grpc_ssl_certificate_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_certificate_key` файл; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с секретным ключом в формате PEM для аутентификации на gRPC SSL-сервере.
Вместо файла можно указать значение "engine:имя:id", которое загружает ключ с указанным id из OpenSSL engine с заданным именем.
Вместо файла можно указать значение "store:scheme:id", которое используется для загрузки ключа с указанным id и URI-схемой scheme, зарегистрированной в OpenSSL provider, например [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).
В имени файла можно использовать переменные.
### grpc_ssl_ciphers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_ciphers` шифры; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `grpc_ssl_ciphers DEFAULT;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Описывает разрешенные шифры для запросов к gRPC SSL-серверу. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL.
Список шифров зависит от установленной версии OpenSSL.
Полный список можно посмотреть с помощью команды `openssl ciphers`.
#### WARNING
Директива `grpc_ssl_ciphers` *не* настраивает шифры для TLS 1.3 при
использовании OpenSSL. Для настройки шифров TLS 1.3 в OpenSSL используйте
директиву [grpc_ssl_conf_command](#grpc-ssl-conf-command), добавленную для расширенной
конфигурации SSL.
- В LibreSSL шифры TLS 1.3 *можно* настраивать с помощью
`grpc_ssl_ciphers`.
- В BoringSSL шифры TLS 1.3 настроить невозможно.
### grpc_ssl_conf_command
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_conf_command` имя значение; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает произвольные конфигурационные [команды](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) OpenSSL при установлении соединения с gRPC SSL-сервером.
#### NOTE
Директива поддерживается при использовании OpenSSL 1.0.2 и выше.
Чтобы настроить шифры TLS 1.3 в OpenSSL, используйте команду `ciphersuites`.
На одном уровне может быть указано несколько директив grpc_ssl_conf_command. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы grpc_ssl_conf_command.
#### WARNING
Следует учитывать, что изменение настроек OpenSSL напрямую может привести к неожиданному поведению.
### grpc_ssl_crl
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_crl` файл; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Указывает файл с отозванными сертификатами (CRL) в формате PEM, используемыми при [проверке](#grpc-ssl-verify) сертификата gRPC SSL-сервера.
### grpc_ssl_name
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_name` имя; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `grpc_ssl_name `имя хоста` из grpc_pass;\` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет переопределить имя сервера, используемое при [проверке](#grpc-ssl-verify) сертификата gRPC SSl-сервера, а также для [передачи его через SNI](#grpc-ssl-server-name) при установлении соединения с gRPC SSL-сервером.
По умолчанию используется имя хоста из [grpc_pass](#grpc-pass).
### grpc_ssl_password_file
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_password_file` файл; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с паролями от [секретных ключей](#grpc-ssl-certificate-key), где каждый пароль указан на отдельной строке. Пароли применяются по очереди в момент загрузки ключа.
### grpc_ssl_protocols
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| По умолчанию | `grpc_ssl_protocols TLSv1.2 TLSv1.3;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает указанные протоколы для запросов к gRPC SSL-серверу.
### grpc_ssl_server_name
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_server_name` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `grpc_ssl_server_name off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает передачу имени сервера,
заданного директивой [grpc_ssl_name](#grpc-ssl-name),
через расширение
[Server Name Indication](http://en.wikipedia.org/wiki/Server_Name_Indication)
протокола TLS
(SNI,
[RFC 6066](https://datatracker.ietf.org/doc/html/rfc6066.html))
при установлении соединения с SSL-сервером gRPC.
### grpc_ssl_session_reuse
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_session_reuse` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `grpc_ssl_session_reuse on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, использовать ли повторно SSL-сессии при работе с gRPC-сервером. Если в логах появляются ошибки "SSL3_GET_FINISHED:digest check failed", то можно попробовать выключить повторное использование сессий.
### grpc_ssl_trusted_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_trusted_certificate` файл; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с доверенными сертификатами CA в формате PEM, используемыми при [проверке](#grpc-ssl-verify) сертификата gRPC SSL-сервера.
### grpc_ssl_verify
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_verify` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `grpc_ssl_verify off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает проверку сертификата gRPC SSL-сервера.
### grpc_ssl_verify_depth
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_verify_depth` число; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `grpc_ssl_verify_depth 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Устанавливает глубину проверки в цепочке сертификатов gRPC SSL-сервера.
# https://angie.software/angie/docs/configuration/modules/http/http_gunzip.md
# GunZIP
Фильтр, распаковывающий ответы с `Content-Encoding: gzip` для тех клиентов, которые не поддерживают метод сжатия "gzip". Модуль будет полезен, когда данные желательно хранить сжатыми для экономии места и сокращения затрат на ввод-вывод.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-http_gunzip_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
## Пример конфигурации
```nginx
location /storage/ {
gunzip on;
# ...
}
```
## Директивы
### gunzip
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gunzip` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию | `gunzip off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает распаковку ответов, сжатых методом gzip, для тех клиентов, которые его не поддерживают. Если разрешено, то для определения, поддерживает ли клиент gzip, также учитываются следующие директивы: [gzip_http_version](https://angie.software//angie/docs/configuration/modules/http/http_gzip.md#gzip-http-version), [gzip_proxied](https://angie.software//angie/docs/configuration/modules/http/http_gzip.md#gzip-proxied) и [gzip_disable](https://angie.software//angie/docs/configuration/modules/http/http_gzip.md#gzip-disable). См. также директиву [gzip_vary](https://angie.software//angie/docs/configuration/modules/http/http_gzip.md#gzip-vary).
### gunzip_buffers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gunzip_buffers` число размер; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `gunzip_buffers 32 4k | 16 8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число и размер буферов, в которые будет разжиматься ответ. По умолчанию размер одного буфера равен размеру страницы. В зависимости от платформы это или 4K, или 8K.
# https://angie.software/angie/docs/configuration/modules/http/http_gzip.md
# GZip
Фильтр, сжимающий ответ методом gzip, что позволяет уменьшить размер передаваемых данных в 2 и более раз.
#### WARNING
При использовании протокола SSL/TLS сжатые ответы могут быть подвержены атакам [BREACH](https://en.wikipedia.org/wiki/BREACH).
## Пример конфигурации
```nginx
gzip on;
gzip_min_length 1000;
gzip_proxied expired no-cache no-store private auth;
gzip_types text/plain application/xml;
```
Для записи в лог достигнутого коэффициента сжатия можно использовать переменную [$gzip_ratio](#v-gzip-ratio).
## Директивы
### gzip
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `gzip off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Разрешает или запрещает сжатие ответа методом gzip.
### gzip_buffers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip_buffers` число размер; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `gzip_buffers 32 4k | 16 8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число и размер буферов, в которые будет сжиматься ответ. По умолчанию размер одного буфера равен размеру страницы. В зависимости от платформы это или 4K, или 8K.
### gzip_comp_level
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip_comp_level` степень; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `gzip_comp_level 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Устанавливает степень сжатия ответа методом gzip. Допустимые значения находятся в диапазоне от 1 до 9.
### gzip_disable
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip_disable` regex ...; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Запрещает сжатие ответа методом gzip для запросов с полями заголовка `User-Agent`, совпадающими с заданными регулярными выражениями.
Специальная маска `msie6` соответствует регулярному выражению "MSIE [4-6].", но работает быстрее. Из этой маски исключается "MSIE 6.0; ... SV1".
### gzip_http_version
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip_http_version` `1.0` | `1.1`; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `gzip_http_version 1.1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Устанавливает минимальную HTTP-версию запроса, необходимую для сжатия ответа.
### gzip_min_length
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip_min_length` длина; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `gzip_min_length 20;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Устанавливает минимальную длину ответа, который будет сжиматься методом gzip. Длина определяется только из поля `Content-Length` заголовка ответа.
### gzip_proxied
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip_proxied` `off` | `expired` | `no-cache` | `no-store` | `private` | `no_last_modified` | `no_etag` | `auth` | `any` ...; |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `gzip_proxied off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает сжатие ответа методом gzip для проксированных запросов в зависимости от запроса и ответа. То, что запрос проксированный, определяется на основании наличия поля `Via` в заголовке запроса. В директиве можно указать одновременно несколько параметров:
| `off` | запрещает сжатие для всех проксированных запросов, игнорируя остальные параметры; |
|--------------------|------------------------------------------------------------------------------------------------------|
| `expired` | разрешает сжатие, если в заголовке ответа есть поле `Expires` со значением, запрещающим кэширование; |
| `no-cache` | разрешает сжатие, если в заголовке ответа есть поле `Cache-Control` с параметром "no-cache"; |
| `no-store` | разрешает сжатие, если в заголовке ответа есть поле `Cache-Control` с параметром "no-store"; |
| `private` | разрешает сжатие, если в заголовке ответа есть поле `Cache-Control` с параметром "private"; |
| `no_last_modified` | разрешает сжатие, если в заголовке ответа нет поля `Last-Modified`; |
| `no_etag` | разрешает сжатие, если в заголовке ответа нет поля `ETag`; |
| `auth` | разрешает сжатие, если в заголовке запроса есть поле `Authorization`; |
| `any` | разрешает сжатие для всех проксированных запросов. |
### gzip_types
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip_types` mime-тип ...; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `gzip_types text/html;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает сжатие ответа методом gzip для указанных MIME-типов в дополнение к `text/html`. Специальное значение "\*" соответствует любому MIME-типу. Ответы с типом `text/html` сжимаются всегда.
### gzip_vary
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip_vary` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `gzip_vary off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает выдавать в ответе поле заголовка "Vary: Accept-Encoding", если активны директивы [gzip](#id3), [gzip_static](https://angie.software//angie/docs/configuration/modules/http/http_gzip_static.md#id3) или [gunzip](https://angie.software//angie/docs/configuration/modules/http/http_gunzip.md#id3).
## Встроенные переменные
### `$gzip_ratio`
достигнутый коэффициент сжатия — отношение размера исходного ответа к размеру сжатого.
# https://angie.software/angie/docs/configuration/modules/http/http_gzip_static.md
# GZip Static
Позволяет отдавать вместо обычного файла предварительно сжатый файл с таким же именем и с расширением ".gz".
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_gzip_static_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
## Пример конфигурации
```nginx
gzip_static on;
gzip_proxied expired no-cache no-store private auth;
```
## Директивы
### gzip_static
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip_static` `on` | `off` | `always`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `gzip_static off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает (`on`) или запрещает (`off`) проверку готового сжатого файла. При использовании также учитываются директивы [gzip_http_version](https://angie.software//angie/docs/configuration/modules/http/http_gzip.md#gzip-http-version), [gzip_proxied](https://angie.software//angie/docs/configuration/modules/http/http_gzip.md#gzip-proxied), [gzip_disable](https://angie.software//angie/docs/configuration/modules/http/http_gzip.md#gzip-disable) и [gzip_vary](https://angie.software//angie/docs/configuration/modules/http/http_gzip.md#gzip-vary).
Со значением `always` во всех случаях будет использоваться сжатый файл, без проверки поддержки на стороне клиента. Это полезно, если на диске все равно нет несжатых файлов, или используется модуль [GunZIP](https://angie.software//angie/docs/configuration/modules/http/http_gunzip.md#http-gunzip).
Сжимать файлы можно с помощью программы gzip или совместимой с ней. Желательно, чтобы дата и время модификации исходного и сжатого файлов совпадали.
# https://angie.software/angie/docs/configuration/modules/http/http_headers.md
# Headers
Позволяет выдавать поля заголовка `Expires` и `Cache-Control`, а также добавлять произвольные поля в заголовок ответа.
## Пример конфигурации
```nginx
expires 24h;
expires modified +24h;
expires @24h;
expires 0;
expires -1;
expires epoch;
expires $expires;
add_header Cache-Control private;
```
## Директивы
### add_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `add_header` имя значение [`always`]; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Добавляет указанное поле в заголовок ответа при условии, что код ответа равен 200, 201 (1.3.10), 204, 206, 301, 302, 303, 304, 307 или 308. В значении параметра можно использовать переменные.
Директив add_header может быть несколько. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы add_header.
Если указан параметр `always`, то поле заголовка будет добавлено независимо от кода ответа.
### add_trailer
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `add_trailer` имя значение [`always`]; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Добавляет указанное поле в конец ответа при условии, что код ответа равен 200, 201, 206, 301, 302, 303, 307 или 308. В значении можно использовать переменные.
Директив add_trailer может быть несколько. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы add_trailer.
Если указан параметр `always`, то указанное поле будет добавлено независимо от кода ответа.
### expires
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `expires` [`modified`] время;
`expires` `epoch` | `max` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| По умолчанию | `expires off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Разрешает или запрещает добавлять или менять поля `Expires` и `Cache-Control` в заголовке ответа при условии, что код ответа равен 200, 201, 204, 206, 301, 302, 303, 304, 307 или 308. В качестве параметра можно задать положительное или отрицательное [время](https://angie.software//angie/docs/configuration/configfile.md#syntax).
Время в поле `Expires` получается как сумма текущего времени и времени, заданного в директиве. Если используется параметр `modified`, то время получается как сумма времени модификации файла и времени, заданного в директиве.
Кроме того, с помощью префикса "@" можно задать время суток:
```nginx
expires @15h30m;
```
Содержимое поля `Cache-Control` зависит от знака заданного времени:
* отрицательное время — "Cache-Control: no-cache".
* положительное или равное нулю время — "Cache-Control: max-age=\`t\`", где t это время в секундах, заданное в директиве.
| `epoch` | задает время "Thu, 01 Jan 1970 00:00:01 GMT" (1 января 1970 00:00:01 GMT) для поля `Expires` и "no-cache" для поля `Cache-Control`. |
|-----------|---------------------------------------------------------------------------------------------------------------------------------------|
| `max` | задает время "Thu, 31 Dec 2037 23:55:55 GMT" (31 декабря 2037 23:55:55 GMT) для поля `Expires` и 10 лет для поля `Cache-Control`. |
| `off` | запрещает добавлять или менять поля `Expires` и `Cache-Control` в заголовке ответа. |
В значении последнего параметра можно использовать переменные:
```nginx
map $sent_http_content_type $expires {
default off;
application/pdf 42d;
~image/ max;
}
expires $expires;
```
# https://angie.software/angie/docs/configuration/modules/http/http_image_filter.md
# Image Filter
Фильтр для преобразования изображений в форматах JPEG, GIF, PNG, WebP, HEIC и AVIF.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_image_filter_module`.
В наших репозиториях модуль собран [динамически](https://angie.software//angie/docs/installation/index.md#install-dynamicmodules) и
доступен отдельным пакетом angie-module-image-filter или angie-pro-module-image-filter.
#### NOTE
Для этого модуля необходима библиотека [libgd](http://libgd.org/). Рекомендуется использовать самую последнюю версию библиотеки.
Для преобразования изображений в форматах WebP, HEIC и AVIF библиотека
libgd должна быть собрана с поддержкой этих форматов.
## Пример конфигурации
```nginx
location /img/ {
proxy_pass http://backend;
image_filter resize 150 100;
image_filter rotate 90;
error_page 415 = /empty;
}
location = /empty {
empty_gif;
}
```
## Директивы
### image_filter
#### Versionchanged
Изменено в версии 1.11.0.
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | - `image_filter` `off`;
- `image_filter` `test`;
- `image_filter` `size`;
- `image_filter` rotate `90` | `180` | `270`;
- `image_filter` resize ширина высота;
- `image_filter` crop ширина высота;
- `image_filter` convert тип; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `image_filter off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Задает тип преобразования изображения:
| `off` | отключает обработку данным модулем во вложенном location. |
|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `test` | проверяет, что ответ действительно является изображением в формате JPEG, GIF, PNG, WebP, HEIC или AVIF. В противном случае возвращается ошибка 415 (Unsupported Media Type). |
| `size` | выдает информацию об изображении в формате JSON, например:
` *"img" : { "width": 100, "height": 100, "type": "gif"* }`
В случае ошибки выдается `{}` |
| `rotate 90|180|270` | поворачивает изображение против часовой стрелки на указанное число градусов. В значении параметра допустимо использование переменных. Можно использовать как отдельно, так и совместно с преобразованиями resize и crop. |
| `resize` ширина высота | пропорционально уменьшает изображение до указанных размеров. Если требуется уменьшить только по одному измерению, то в качестве второго можно указать "-". В случае ошибки сервер возвращает код 415 (Unsupported Media Type). В значениях параметров допустимо использование переменных. При использовании совместно с rotate, поворот изображения происходит **после** уменьшения размеров изображения. |
| `crop` ширина высота | пропорционально уменьшает изображение до размера большей стороны и обрезает лишние края по другой стороне. Если требуется уменьшить только по одному измерению, то в качестве второго можно указать "-". В случае ошибки сервер возвращает код 415 (Unsupported Media Type). В значениях параметров допустимо использование переменных. При использовании совместно с rotate, поворот изображения происходит **до** уменьшения размеров изображения. |
| `convert` тип | преобразует изображение в указанный выходной формат. Допустимые значения:
`jpeg`, `gif`, `png`, `webp`, `heic`
и `avif`. В значении параметра допустимо использование переменных. |
### image_filter_buffer
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `image_filter_buffer` размер; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `image_filter_buffer 1M;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает максимальный размер буфера для чтения изображения. При превышении размера сервер вернет ошибку 415 (Unsupported Media Type).
### image_filter_interlace
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `image_filter_interlace` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `image_filter_interlace off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если включено, то итоговые изображения будут с чересстрочностью. В случае JPEG итоговые изображения будут в формате "progressive JPEG".
### image_filter_jpeg_quality
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `image_filter_jpeg_quality` качество; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `image_filter_jpeg_quality 75;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает желаемое качество преобразованного изображения в формате JPEG. Допустимые значения находятся в диапазоне от 1 до 100. Меньшим значениям обычно соответствует худшее качество изображения и меньший объем передаваемых данных. Максимальное рекомендуемое значение — 95. В значении параметра допустимо использование переменных.
### image_filter_sharpen
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `image_filter_sharpen` процент; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `image_filter_sharpen 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Повышает резкость итогового изображения. Процент резкости может быть больше 100. Значение `0` отключает повышение резкости. В значении параметра допустимо использование переменных.
### image_filter_transparency
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `image_filter_transparency` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | `image_filter_transparency on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, сохранять ли прозрачность при обработке изображений в формате GIF и в формате PNG с цветами, заданными палитрой. Потеря прозрачности позволяет получить более качественное изображение. Прозрачность альфа-канала в формате PNG сохраняется всегда.
### image_filter_webp_quality
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `image_filter_webp_quality` качество; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `image_filter_webp_quality 80;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает желаемое качество преобразованного изображения в формате WebP. Допустимые значения находятся в диапазоне от 1 до 100. Меньшим значениям обычно соответствует худшее качество изображения и меньший объем передаваемых данных. В значении параметра допустимо использование переменных.
### image_filter_heic_quality
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `image_filter_heic_quality` качество; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `image_filter_heic_quality 80;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает желаемое качество преобразованного изображения в формате HEIC. Допустимые значения — положительные числа. В значении параметра допустимо использование переменных.
### image_filter_avif_quality
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `image_filter_avif_quality` качество [скорость]; |
|------------------------------------------------------------------------------------------|----------------------------------------------------|
| По умолчанию | `image_filter_avif_quality 80 6;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает желаемое качество преобразованного изображения в формате AVIF. Необязательный параметр `скорость` управляет скоростью кодирования; оба значения должны быть положительными числами. В значениях параметров допустимо использование переменных.
# https://angie.software/angie/docs/configuration/modules/http/http_index.md
# Index
Обслуживает запросы, оканчивающиеся косой чертой (`/`). Такие запросы также могут обслуживаться модулями [AutoIndex](https://angie.software//angie/docs/configuration/modules/http/http_autoindex.md#http-autoindex) и [Random Index](https://angie.software//angie/docs/configuration/modules/http/http_random_index.md#http-random-index).
## Пример конфигурации
```nginx
location / {
index index.$geo.html index.html;
}
```
## Директивы
### index
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `index` файл ...; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | `index index.html;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет файлы, которые будут использоваться в качестве индекса. В имени файла можно использовать переменные. Наличие файлов проверяется в порядке их перечисления. В конце списка может стоять файл с абсолютным путем. Пример:
```nginx
index index.$geo.html index.0.html /index.html;
```
Необходимо иметь в виду, что при использовании индексного файла делается внутреннее перенаправление и запрос может быть обработан уже в другом `location`. Например, в такой конфигурации:
```nginx
location = / {
index index.html;
}
location / {
# ...
}
```
запрос `"/"` будет фактически обработан во втором `location` как "/index.html".
# https://angie.software/angie/docs/configuration/modules/http/http_limit_conn.md
# Limit Conn
Позволяет ограничить число соединений по заданному ключу, в частности, число соединений с одного IP-адреса.
Учитываются не все соединения, а лишь те, в которых имеются запросы, обрабатываемые сервером, и заголовок запроса уже прочитан.
## Пример конфигурации
```nginx
http {
limit_conn_zone $binary_remote_addr zone=addr:10m;
...
server {
...
location /download/ {
limit_conn addr 1;
}
```
## Директивы
### limit_conn
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_conn` зона число; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает зону разделяемой памяти и максимально допустимое число соединений для одного значения ключа. При превышении этого числа в ответ на запрос сервер вернет [ошибку](#limit-conn-status). Например, директивы
```nginx
limit_conn_zone $binary_remote_addr zone=addr:10m;
server {
location /download/ {
limit_conn addr 1;
}
```
разрешают одновременно обрабатывать не более одного соединения с одного IP-адреса.
#### NOTE
В HTTP/2 и HTTP/3 каждый параллельный запрос считается отдельным соединением.
Директив limit_conn может быть несколько. Например, следующая конфигурация ограничивает число соединений с сервером с одного клиентского IP-адреса и в то же время ограничивает общее число соединений с виртуальным сервером:
```nginx
limit_conn_zone $binary_remote_addr zone=perip:10m;
limit_conn_zone $server_name zone=perserver:10m;
server {
...
limit_conn perip 10;
limit_conn perserver 100;
}
```
Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы limit_conn.
### limit_conn_dry_run
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_conn_dry_run` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `limit_conn_dry_run off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Включает режим пробного запуска. В данном режиме число соединений не ограничивается, однако в [зоне разделяемой памяти](#limit-conn-zone) текущее число избыточных соединений учитывается как обычно.
### limit_conn_log_level
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_conn_log_level` `info` | `notice` | `warn` | `error`; |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------|
| По умолчанию | `limit_conn_log_level error;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает желаемый уровень записи в лог случаев ограничения числа соединений.
### limit_conn_status
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_conn_status` код; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `limit_conn_status 503;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет переопределить код ответа, используемый при отклонении запросов.
### limit_conn_zone
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_conn_zone` ключ zone = название:размер; |
|------------------------------------------------------------------------------------------|--------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает параметры зоны разделяемой памяти, которая хранит состояние для разных значений ключа. Состояние в частности содержит текущее число соединений. В качестве ключа можно использовать текст, переменные и их комбинации. Запросы с пустым значением ключа не учитываются.
Пример использования:
```nginx
limit_conn_zone $binary_remote_addr zone=addr:10m;
```
Здесь в качестве ключа используется IP-адрес клиента. Обратите внимание, что вместо переменной `$remote_addr` использована переменная `$binary_remote_addr`.
Длина значения переменной `$remote_addr` может колебаться от 7 до 15 байт, при этом размер хранимого состояния составляет либо 32, либо 64 байта на 32-битных платформах и всегда 64 байта на 64-битных.
Длина значения переменной `$binary_remote_addr` всегда равна 4 байтам для IPv4-адресов или 16 байтам для IPv6-адресов. При этом размер состояния всегда равен 32 или 64 байтам на 32-битных платформах и 64 байтам на 64-битных.
В зоне размером 1 мегабайт может разместиться около 32 тысяч состояний размером 32 байта или 16 тысяч состояний размером 64 байта. При переполнении зоны в ответ на последующие запросы сервер будет возвращать [ошибку](#limit-conn-status).
## Встроенные переменные
### `$limit_conn_status`
хранит результат ограничения числа соединений: PASSED, REJECTED или REJECTED_DRY_RUN
# https://angie.software/angie/docs/configuration/modules/http/http_limit_req.md
# Limit Req
Позволяет ограничить скорость обработки запросов по заданному ключу или, как частный случай, скорость обработки запросов, поступающих с одного IP-адреса. Ограничение обеспечивается с помощью метода "leaky bucket".
## Пример конфигурации
```nginx
http {
limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
...
server {
...
location /search/ {
limit_req zone=one burst=5;
}
```
## Директивы
### limit_req
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_req` `zone=`название [`burst=`число] [nodelay | `delay=`число]; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает зону разделяемой памяти (`zone`) и максимальный размер всплеска запросов (`burst`). Если скорость поступления запросов превышает описанную в зоне, то их обработка задерживается так, чтобы запросы обрабатывались с заданной скоростью. Избыточные запросы задерживаются до тех пор, пока их число не превысит максимальный размер всплеска. При превышении запрос завершается с ошибкой. По умолчанию максимальный размер всплеска равен нулю. Например, директивы
```nginx
limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
server {
location /search/ {
limit_req zone=one burst=5;
}
```
позволяют в среднем не более 1 запроса в секунду со всплесками не более 5 запросов.
Если же избыточные запросы в пределах лимита всплесков задерживать не требуется, то следует использовать параметр `nodelay`:
```nginx
limit_req zone=one burst=5 nodelay;
```
Параметр `delay` задает лимит, по достижении которого избыточные запросы задерживаются. Значение по умолчанию равно нулю и означает, что задерживаются все избыточные запросы.
Директив `limit_req` может быть несколько. Например, следующая конфигурация ограничивает скорость обработки запросов, поступающих с одного IP-адреса, и в то же время ограничивает скорость обработки запросов одним виртуальным сервером:
```nginx
limit_req_zone $binary_remote_addr zone=perip:10m rate=1r/s;
limit_req_zone $server_name zone=perserver:10m rate=10r/s;
server {
...
limit_req zone=perip burst=5 nodelay;
limit_req zone=perserver burst=10;
}
```
Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы `limit_req`.
### limit_req_dry_run
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_req_dry_run` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `limit_req_dry_run off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Включает режим пробного запуска. В данном режиме скорость обработки запросов не ограничивается, однако в [зоне разделяемой памяти](#limit-req-zone) текущее число избыточных запросов учитывается как обычно.
### limit_req_log_level
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_req_log_level` `info` | `notice` | `warn` | `error`; |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------|
| По умолчанию | `limit_req_log_level error;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает желаемый уровень записи в лог случаев отказа в обработке запросов при превышении скорости и случаев задержек при обработке запроса. Задержки записываются в лог с уровнем на единицу меньшим, чем отказы, например, если указано `limit_req_log_level notice;`, то задержки будут записываться в лог на уровне `info`.
### limit_req_status
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_req_status` код; |
|------------------------------------------------------------------------------------------|---------------------------|
| По умолчанию | `limit_req_status 503;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет переопределить код ответа, используемый при отклонении запросов.
### limit_req_zone
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_req_zone` ключ `zone=`название:размер `rate=`скорость; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает параметры зоны разделяемой памяти, которая хранит состояние для разных значений ключа. Состояние в частности хранит текущее число избыточных запросов. В качестве ключа можно использовать текст, переменные и их комбинации. Запросы с пустым значением ключа не учитываются.
Пример использования:
```nginx
limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
```
В данном случае состояния хранятся в зоне `one` размером 10 мегабайт, и средняя скорость обработки запросов для этой зоны не может превышать 1 запроса в секунду.
В качестве ключа используется IP-адрес клиента. Обратите внимание, что вместо переменной `$remote_addr` используется переменная `$binary_remote_addr`.
Длина значения переменной `$binary_remote_addr` всегда равна 4 байтам для IPv4-адресов или 16 байтам для IPv6-адресов. При этом размер состояния всегда равен 64 байтам на 32-битных платформах и 128 байтам на 64-битных платформах.
В зоне размером 1 мегабайт может разместиться около 16 тысяч состояний размером 64 байта или около 8 тысяч состояний размером 128 байт.
При переполнении зоны удаляется наименее востребованное состояние. Если и это не позволяет создать новое состояние, запрос завершается с [ошибкой](#limit-req-status).
Скорость `rate` задается в запросах в секунду (r/s). Если же нужна скорость меньше одного запроса в секунду, то она задается в запросах в минуту (r/m), например, ползапроса в секунду — это 30r/m.
## Встроенные переменные
### `$limit_req_status`
хранит результат ограничения скорости поступления запросов: `PASSED`, `DELAYED`, `REJECTED`, `DELAYED_DRY_RUN` или `REJECTED_DRY_RUN`
# https://angie.software/angie/docs/configuration/modules/http/http_log.md
# Log
Модуль записывает логи запросов в указанном формате.
Логи записываются в контексте `location`, где заканчивается обработка. Это может быть `location`, отличный от первоначального, если в процессе обработки запроса происходит [внутреннее перенаправление](https://angie.software//angie/docs/configuration/modules/http/index.md#internal).
## Пример конфигурации
```nginx
log_format compression '$remote_addr - $remote_user [$time_local] '
'"$request" $status $bytes_sent '
'"$http_referer" "$http_user_agent" "$gzip_ratio"';
access_log /spool/logs/angie-access.log compression buffer=32k;
```
## Директивы
### access_log
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `access_log` путь [формат [`buffer=`размер] [`gzip=`степень]] [`flush=`время] [`if=`условие]];
`access_log` `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `access_log logs/access.log combined;`
(путь зависит от [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-log-path`) |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location, limit_except |
Задает путь, формат и настройки буферизованной записи в лог. На одном уровне конфигурации может использоваться несколько логов. Запись в [syslog](https://angie.software//angie/docs/configuration/processing.md#syslog-logging) настраивается указанием префикса "syslog:" в первом параметре. Специальное значение off отменяет все директивы access_log для текущего уровня. Если формат не указан, то используется предопределенный формат "combined".
Если задан размер буфера с помощью параметра `buffer` или указан параметр `gzip`, то запись будет буферизованной.
#### WARNING
Размер буфера должен быть не больше размера атомарной записи в дисковый файл. Для FreeBSD этот размер неограничен.
При включенной буферизации данные записываются в файл:
* если очередная строка лога не помещается в буфер;
* если данные в буфере находятся дольше интервала времени, заданного параметром flush;
* при [переоткрытии лог-файла](https://angie.software//angie/docs/configuration/runtime.md#log-rotation) или завершении рабочего процесса.
Если задан параметр `gzip`, то буфер будет сжиматься перед записью в файл. Степень сжатия может быть задана в диапазоне от 1 (быстрее, но хуже сжатие) до 9 (медленнее, но лучше сжатие). По умолчанию используются буфер размером 64К байт и степень сжатия 1. Данные сжимаются атомарными блоками, и в любой момент времени лог-файл может быть распакован или прочитан с помощью утилиты **zcat**.
Пример:
```nginx
access_log /path/to/log.gz combined gzip flush=5m;
```
#### NOTE
Для поддержки gzip-сжатия логов Angie должен быть собран с библиотекой zlib.
В пути файла можно использовать переменные, но такие логи имеют некоторые ограничения:
* [пользователь](https://angie.software//angie/docs/configuration/modules/core.md#user), с правами которого работают рабочие процессы, должен иметь права на создание файлов в каталоге с такими логами;
* не работает буферизация;
* файл открывается для каждой записи в лог и сразу же после записи закрывается. Следует однако иметь в виду, что поскольку дескрипторы часто используемых файлов могут храниться в кэше, то при ротации логов в течение времени, заданного параметром valid директивы [open_log_file_cache](#open-log-file-cache), запись может продолжаться в старый файл.
* при каждой записи в лог проверяется существование корневого каталога для запроса — если этот каталог не существует, то лог не создается. Поэтому [root](https://angie.software//angie/docs/configuration/modules/http/index.md#root) и [access_log](#access-log) нужно описывать на одном уровне конфигурации:
```nginx
server {
root /spool/vhost/data/$host;
access_log /spool/vhost/logs/$host;
...
```
Параметр `if` включает условную запись в лог. Запрос не будет записываться в лог, если результатом вычисления условия является `"0"` или пустая строка. В следующем примере запросы с кодами ответа 2xx и 3xx не будут записываться в лог:
```nginx
map $status $loggable {
~^[23] 0;
default 1;
}
access_log /path/to/access.log combined if=$loggable;
```
### log_format
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `log_format` имя [`escape`= `default` | `json` | `none` ] строка ...; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
| По умолчанию | `log_format combined "...";` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает формат лога.
Параметр `escape` позволяет задать экранирование символов `json` или
`default` в переменных, по умолчанию используется `default`.
Значение `none` отключает экранирование символов.
При использовании `default` символы """, "\\", а также символы со
значениями меньше 32 или больше 126 экранируются как "\\xXX". Если значение
переменной не найдено, то в качестве значения в лог будет записываться дефис
"-".
При использовании `json` экранируются все символы, недопустимые в JSON
строках: символы """ и "\\" экранируются как "\\"" и "\\\\", символы со
значениями меньше 32 экранируются как "\\n", "\\r", "\\t", "\\b", "\\f" или
"\\u00XX".
Строки заголовка, переданные клиенту, начинаются с префикса `sent_http_`,
например, `$sent_http_content_range`.
В конфигурации всегда существует предопределенный формат `combined`:
```nginx
log_format combined '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent"';
```
### open_log_file_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `open_log_file_cache` `max=`N [`inactive=`время] [`min_uses=`N] [`valid=`время];
`open_log_file_cache` `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `open_log_file_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает кэш, в котором хранятся дескрипторы файлов часто используемых логов, имена которых заданы с использованием переменных. Параметры:
| `max` | Задает максимальное число дескрипторов в кэше; при переполнении кэша наименее востребованные (LRU) дескрипторы закрываются. |
|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `inactive` | Задает время, после которого кэшированный дескриптор закрывается, если к нему не было обращений в течение этого времени.
По умолчанию — 10 секунд. |
| `min_uses` | Задает минимальное число использований файла в течение времени, заданного параметром `inactive`, после которого дескриптор файла будет оставаться открытым в кэше.
По умолчанию — 1. |
| `valid` | Указыает, через какое время нужно проверять, что файл еще существует под тем же именем.
По умолчанию — 60 секунд. |
| `off` | Запрещает кэширование. |
Пример использования:
```nginx
open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;
```
# https://angie.software/angie/docs/configuration/modules/http/http_map.md
# Map
Создает переменные, значения которых зависят от значений других переменных.
## Пример конфигурации
```nginx
map $http_host $name {
hostnames;
default 0;
example.com 1;
*.example.com 1;
example.org 2;
*.example.org 2;
.example.net 3;
wap.* 4;
}
map $http_user_agent $mobile {
default 0;
"~Opera Mini" 1;
}
```
## Директивы
### map
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `map` строка $переменная { ... } |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Создает новую переменную.
Ее значение зависит от первого параметра, заданного строкой с переменными,
например:
```nginx
set $var1 "foo";
set $var2 "bar";
map $var1$var2 $new_variable {
default "foobar_value";
}
```
Здесь переменная `$new_variable` будет иметь значение,
составленное из двух переменных `$var1` и `$var2`,
или значение по умолчанию, если эти переменные не определены.
#### NOTE
Поскольку переменные вычисляются только в момент использования, само по себе наличие даже большого числа объявлений переменных "map" не влечет за собой никаких дополнительных расходов на обработку запросов.
Параметры внутри блока `map` задают соответствие между исходными и результирующими значениями.
Исходные значения задаются строками или регулярными выражениями.
Строки проверяются без учета регистра.
Перед регулярным выражением ставится символ `~`, если при сравнении
следует учитывать регистр символов, либо символы `~*`, если регистр
символов учитывать не нужно. Регулярное выражение может содержать именованные и
позиционные группы захвата, которые могут затем использоваться в других
директивах совместно с результирующей переменной.
Если исходное значение совпадает с именем одного из специальных параметров,
описанных ниже, перед ним следует поставить символ `\`.
В качестве результирующего значения можно указать текст, переменную и их комбинации.
Также поддерживаются следующие специальные параметры:
| `default` значение | задает результирующее значение, если исходное значение не совпадает ни с одним из перечисленных. Если параметр default не указан, результирующим значением по умолчанию будет пустая строка. |
|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `hostnames` | указывает, что в качестве исходных значений можно использовать маску для первой или последней части имени хоста. Этот параметр следует указывать перед списком значений. |
Например,
```nginx
*.example.com 1;
example.* 1;
```
Вместо двух записей
```nginx
example.com 1;
*.example.com 1;
```
можно использовать одну:
```nginx
.example.com 1;
```
| `include` файл | включает файл со значениями. Включений может быть несколько. |
|------------------|----------------------------------------------------------------|
| `volatile` | указывает, что переменная не кэшируется. |
Если исходному значению соответствует несколько из указанных вариантов, например, одновременно подходят и маска, и регулярное выражение, будет выбран первый подходящий вариант в следующем порядке приоритета:
1. Строковое значение без маски.
2. Самое длинное строковое значение с маской в начале, например "`*.example.com`".
3. Самое длинное строковое значение с маской в конце, например "`mail.*`".
4. Первое подходящее регулярное выражение (в порядке следования в конфигурационном файле).
5. Значение по умолчанию (default).
### map_hash_bucket_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `map_hash_bucket_size` размер; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `map_hash_bucket_size 32|64|128;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает размер корзины в хэш-таблицах для переменных [map](#id3). Значение по умолчанию зависит от размера строки кэша процессора. Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
### map_hash_max_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `map_hash_max_size` размер; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `map_hash_max_size 2048;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает максимальный размер хэш-таблиц для переменных [map](#id3). Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
# https://angie.software/angie/docs/configuration/modules/http/http_memcached.md
# Memcached
Позволяет получать ответ из сервера memcached. Ключ задается в переменной [$memcached_key](#v-memcached-key). Ответ в memcached должен быть предварительно помещен внешним по отношению к Angie способом.
## Пример конфигурации
```nginx
server {
location / {
set $memcached_key "$uri?$args";
memcached_pass host:11211;
error_page 404 502 504 = @fallback;
}
location @fallback {
proxy_pass http://backend;
}
}
```
## Директивы
### memcached_bind
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_bind` адрес [`transparent`] | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает локальный IP-адрес с необязательным портом, который будет использоваться в исходящих соединениях с сервером memcached. В значении параметра допустимо использование переменных. Специальное значение `off` отменяет действие унаследованной с предыдущего уровня конфигурации директивы memcached_bind, позволяя системе самостоятельно выбирать локальный IP-адрес и порт.
Параметр `transparent` позволяет задать нелокальный IP-aдрес, который будет использоваться в исходящих соединениях с проксируемым сервером, например, реальный IP-адрес клиента:
```nginx
memcached_bind $remote_addr transparent;
```
Для работы параметра обычно требуется запустить рабочие процессы Angie с привилегиями [суперпользователя](https://angie.software//angie/docs/configuration/modules/core.md#user). В Linux это не требуется, так как если указан параметр transparent, то рабочие процессы наследуют capability CAP_NET_RAW из главного процесса.
#### NOTE
Необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с серверa memcached.
### memcached_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_buffer_size` размер; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `memcached_buffer_size 4k|8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает размер буфера, в который будет читаться первая часть ответа, получаемого от сервера memcached. Ответ синхронно передается клиенту сразу же по мере его поступления.
### memcached_connect_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_connect_timeout` время; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `memcached_connect_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут для установления соединения с сервером memcached. Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.
### memcached_gzip_flag
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_gzip_flag` флаг; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Включает проверку указанного флага в ответе сервера memcached и установку поля `Content-Encoding` заголовка ответа в "gzip", если этот флаг установлен.
### memcached_next_upstream
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_next_upstream` `error` | `timeout` | `invalid_response` | `not_found` | `off` ...; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|
| По умолчанию | `memcached_next_upstream error timeout;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, в каких случаях запрос будет передан следующему в группе [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) серверу:
| `error` | произошла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
|--------------------|-------------------------------------------------------------------------------------------------------------|
| `timeout` | произошел таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
| `invalid_response` | сервер вернул пустой или неверный ответ; |
| `not_found` | сервер не нашел ответ; |
| `off` | запрещает передачу запроса следующему серверу. |
#### NOTE
Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту еще ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа клиенту, то действие директивы на такой запрос не распространяется.
Директива также определяет, что считается [неудачной попыткой](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) работы с сервером.
| `error`, `timeout`, `invalid_response` | Всегда считаются неудачными попытками, даже если они не указаны в директиве. |
|------------------------------------------|--------------------------------------------------------------------------------|
| `not_found` | Никогда не считается неудачными попытками. |
Передача запроса следующему серверу может быть ограничена по [количеству попыток](#memcached-next-upstream-tries) и по [времени](#memcached-next-upstream-timeout).
### memcached_next_upstream_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_next_upstream_timeout` время; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `memcached_next_upstream_timeout 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает время, в течение которого возможна передача запроса [следующему](#memcached-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### memcached_next_upstream_tries
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_next_upstream_tries` число; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `memcached_next_upstream_tries 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает число допустимых попыток для передачи запроса [следующему](#memcached-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### memcached_pass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_pass` адрес; |
|------------------------------------------------------------------------------------------|---------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location, if в location |
Задает адрес сервера memcached. Адрес может быть указан в виде доменного имени или IP-адреса, и порта:
```nginx
memcached_pass localhost:11211;
```
или в виде пути UNIX-сокета:
```nginx
memcached_pass unix:/tmp/memcached.socket;
```
Если доменному имени соответствует несколько адресов, то все они будут использоваться по очереди (round-robin). Кроме того, в качестве адреса можно указать [группу серверов](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).
#### NOTE
Если `memcached_pass` стоит в `location` с косой чертой в конце префикса
(например, `location /name/`),
и при этом в директиве [auto_redirect](https://angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) указано `default`,
запросы без косой черты в конце будут перенаправляться (`/name -> /name/`).
### memcached_read_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_read_timeout` время; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `memcached_read_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при чтении ответа сервера memcached. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени сервер memcached ничего не передаст, соединение закрывается.
### memcached_send_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_send_timeout` время; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `memcached_send_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при передаче запроса серверу memcached. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени сервер memcached не примет новых данных, соединение закрывается.
### memcached_socket_keepalive
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_socket_keepalive` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | `memcached_socket_keepalive off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Конфигурирует поведение "TCP keepalive" для исходящих соединений к проксируемому серверу.
| `""` | По умолчанию для сокета действуют настройки операционной системы. |
|--------|---------------------------------------------------------------------|
| `on` | для сокета включается параметр SO_KEEPALIVE |
## Встроенные переменные
### `$memcached_key`
Задает ключ для получения ответа из сервера memcached.
# https://angie.software/angie/docs/configuration/modules/http/http_metric.md
# Metric
#### Versionadded
Добавлено в версии 1.11.0.
Модуль `ngx_http_metric_module` позволяет создавать вычисляемые в реальном времени
произвольные метрики. Значения таких метрик сохраняются в разделяемой памяти
и отображаются в реальном времени в ветке API `/status/http/metric_zones/`.
Поддерживаются различные типы агрегации данных (счетчики, гистограммы, скользящие средние и др.)
с группировкой по произвольным ключам.
## Пример конфигурации
Подсчет запросов к API:
```nginx
http {
metric_zone api_requests:1m count;
server {
listen 80;
location /api/ {
allow 127.0.0.1;
deny all;
api /status/;
metric api_requests $http_user_agent on=request;
}
}
}
```
Если с такой конфигурацией выполнить запрос на `/api/`:
```console
$ curl 127.0.0.1/api/ --user-agent "Firefox"
```
В реальном времени происходит обновление метрики `api_requests`:
```json
{
"http": {
"metric_zones": {
"api_requests": {
"discarded": 0,
"metrics": {
"Firefox": 1
}
}
}
}
}
```
## Директивы
### metric_zone
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `metric_zone` название:размер [`expire`=`on`| `off`] [`discard_key`=`название`] режим [параметры]; |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Создает зону разделяемой памяти указанного размера с именем название,
в которой хранятся метрики. Имя зоны является узлом в ветке
`/status/http/metric_zones/`.
Параметры:
- `expire=` — поведение при переполнении зоны:
- Если `on`, самые старые метрики по времени обновления отбрасываются,
освобождая память под поступающие;
- Если `off` (по умолчанию) — отбрасываются поступающие метрики,
сохраняя информацию об установленных.
- `discard_key=<название>` — задает метрику с ключом название,
в которой сохраняются значения отброшенных метрик. По умолчанию такая метрика
не создается. Зарезервированный ключ нельзя обновлять вручную.
- режим — алгоритм обработки значений (см. раздел [Режимы работы](#metric-modes));
- параметры — дополнительная настройка выбранного режима
(например, `factor` для `average exp`).
Пример использования:
```nginx
metric_zone request_time:1m max;
```
В API дереве шаблон зоны разделяемой памяти выглядит следующим образом:
```json
{
"discarded": 0,
"metrics": {
"ключ1": 123,
"ключ2": 10.5,
}
}
```
| `discarded` | Число; количество отброшенных метрик в зоне разделяемой памяти |
|---------------|---------------------------------------------------------------------------------|
| `metrics` | Объект; его члены — метрики с установленными ключами и подсчитанными значениями |
#### NOTE
В зоне размером 1 мегабайт при размере ключа 39 байт и с одним режимом
метрики может разместиться около 8 тысяч записей с уникальным ключом.
### metric_complex_zone
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `metric_complex_zone` название:размер [`expire`=`on`| `off`] [`discard_key`=`название`] { ... } |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Определяет составную метрику — набор метрик с независимыми режимами.
Каждая строка в теле блока задает название подметрики, режим
и необязательные параметры режима.
Пример использования:
```nginx
metric_complex_zone requests:1m expire=on discard_key="old" {
# название подметрики режим работы параметры
min_time min;
avg_time average exp factor=60;
max_time max;
total count;
}
```
В API дереве шаблон такой составной метрики выглядит следующим образом:
```json
{
"discarded": 3,
"metrics": {
"ключ1": {
"min_time": 20,
"avg_time": 50,
"max_time": 80,
"total": 2
},
"old": {
"min_time": 3,
"avg_time": 40,
"max_time": 152,
"total": 80
}
}
}
```
| `discarded` | Число; количество отброшенных метрик в зоне разделяемой памяти |
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| `metrics` | Объект; его члены — составные метрики с установленными ключами. Они представляют собой объекты, содержащие набор подметрик с подсчитанными значениями |
### metric
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `metric` название ключ=значение [`on`=`request`| `response`| `end`]; |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Подсчитывает значение метрики с указанным названием зоны разделяемой памяти.
Параметры:
- ключ — произвольная строка (часто переменная), по которой группируются
значения. Максимальная длина — 255 байт. Если ключ длиннее, он будет
ограничен размером 255 байт и дополнен `...` многоточием;
- значение — число (может быть переменной), обрабатываемое выбранным режимом.
Если пропущено, считается `0`. Если параметр невозможно преобразовать
в число, считается `1`;
- `on` — необязательный параметр, указывающий в какой момент происходит
подсчет метрики:
- Если `on=request`, подсчет происходит при получении запроса;
- Если `on=response`, подсчет происходит при подготовке ответа;
- Если `on=end` (по умолчанию), подсчет происходит после отправки ответа.
#### NOTE
В случае внутреннего перенаправления, метрики на стадии `on=request`
посчитаются в исходном `location`. При этом метрики
`on=response` и `on=end` будут подсчитаны уже в новом
`location`.
Пример использования:
```nginx
metric requests $http_user_agent=$request_time;
```
#### NOTE
Метрики с пустым ключом или неправильной парой `ключ=значение`
не учитываются. Пропущенное значение учитывается как `0`:
```nginx
metric foo $bar; # Вместо $bar=0
```
Что полезно, например, для режима `count`, который игнорирует
числовое значение и реагирует на факт обновления метрики.
#### NOTE
Важно помнить, что переменные вычисляются в разных фазах. Например,
невозможно использовать `$bytes_sent` (количество отправленных байт клиенту)
при `on=request` (при получении запроса).
## Режимы работы
Список доступных режимов работы метрик:
* `count` — счетчик обращений;
* `gauge` — стрелка (инкремент/декремент);
* `last` — последнее поступившее значение;
* `min` — минимальное значение;
* `max` — максимальное значение;
* `average exp` — скользящее среднее (параметр `factor`);
* `average mean` — среднее за окно (параметры `window` и `count`);
* `histogram` — распределение по "бакетам" (перечень пороговых значений).
### count
Счетчик увеличивает свое значение на `1` при каждом обновлении метрики.
Значение по умолчанию — `0`.
#### NOTE
Любое обновление метрики (с любым значением) монотонно увеличивает
счетчик на `1`.
Примеры:
```nginx
metric_zone count:1m count;
# В качесте составной метрики:
#
# metric_complex_zone count:1m {
# some_metric_name count;
# }
server {
listen 80;
location /metric/ {
metric count KEY;
}
location ~ ^/metric/set/(.+)$ {
metric count KEY=$1;
}
location /api/ {
api /status/http/metric_zones/count/metrics/;
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/
$ curl 127.0.0.1/metric/set/1
$ curl 127.0.0.1/metric/set/23
$ curl 127.0.0.1/metric/set/-32
```
Ожидаемое значение метрики в API:
```json
{
"KEY": 4
}
```
### gauge
Счетчик увеличивает или уменьшает свое значение в зависимости
от знака переданного числа. При положительном — увеличивает счетчик.
При отрицательном — уменьшает. Переданное значение `0` не изменяет счетчик.
Значение по умолчанию — `0`.
Примеры:
```nginx
metric_zone gauge:1m gauge;
# В качесте составной метрики:
#
# metric_complex_zone gauge:1m {
# some_metric_name gauge;
# }
server {
listen 80;
location /metric/ {
metric gauge KEY;
}
location ~ ^/metric/set/(.+)$ {
metric gauge KEY=$1;
}
location /api/ {
api /status/http/metric_zones/gauge/metrics/;
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/
```
Ожидаемое значение метрики в API:
```json
{
"KEY": 0
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/set/5
$ curl 127.0.0.1/metric/set/-5
$ curl 127.0.0.1/metric/set/8
```
Ожидаемое значение метрики в API:
```json
{
"KEY": 8
}
```
### last
Хранит последнее полученное значение без какой-либо агрегации.
Если значение опущено, используется `0`.
Примеры:
```nginx
metric_zone last:1m last;
# В качесте составной метрики:
#
# metric_complex_zone last:1m {
# some_metric_name last;
# }
server {
listen 80;
location /metric/ {
metric last KEY;
}
location ~ ^/metric/set/(.+)$ {
metric last KEY=$1;
}
location /api/ {
api /status/http/metric_zones/last/metrics/;
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/
```
Ожидаемое значение метрики в API:
```json
{
"KEY": 0
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/set/8000
$ curl 127.0.0.1/metric/set/37
$ curl 127.0.0.1/metric/set/-3.5
```
Ожидаемое значение метрики в API:
```json
{
"KEY": -3.5
}
```
### min
Сохраняет минимальное из двух значений — уже сохраненного и нового.
Примеры:
```nginx
metric_zone min:1m min;
# В качесте составной метрики:
#
# metric_complex_zone min:1m {
# some_metric_name min;
# }
server {
listen 80;
location /metric/ {
metric min KEY;
}
location ~ ^/metric/set/(.+)$ {
metric min KEY=$1;
}
location /api/ {
api /status/http/metric_zones/min/metrics/;
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/set/42.999
$ curl 127.0.0.1/metric/set/-512
$ curl 127.0.0.1/metric/set/1
$ curl 127.0.0.1/metric/
```
Ожидаемое значение метрики в API:
```json
{
"KEY": -512
}
```
### max
Сохраняет наибольшее из двух значений — уже сохраненного и нового.
Примеры:
```nginx
metric_zone max:1m max;
# В качесте составной метрики:
#
# metric_complex_zone max:1m {
# some_metric_name max;
# }
server {
listen 80;
location /metric/ {
metric max KEY;
}
location ~ ^/metric/set/(.+)$ {
metric max KEY=$1;
}
location /api/ {
api /status/http/metric_zones/max/metrics/;
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/set/42.999
$ curl 127.0.0.1/metric/set/-512
$ curl 127.0.0.1/metric/set/1
$ curl 127.0.0.1/metric/
```
Ожидаемое значение метрики в API:
```json
{
"KEY": 42.999
}
```
### average exp
Вычисляет среднее значение по алгоритму
[экспоненциального сглаживания](https://en.wikipedia.org/wiki/Exponential_smoothing).
Принимает необязательный параметр `factor=<число>` — коэффициент,
по которому установленное значение учитывается при расчете среднего.
Допустимы целые числа от `0` до `99`. По умолчанию — `90`.
Чем больше коэффициент, тем сильнее новые значения влияют на среднее.
Если указать `90`, то будет взято `90%` от нового значения
и лишь `10%` от предыдущего.
Примеры:
```nginx
metric_zone avg_exp:1m average exp factor=60;
# В качесте составной метрики:
#
# metric_complex_zone avg_exp:1m {
# some_metric_name average exp factor=60;
# }
server {
listen 80;
location ~ ^/metric/set/(.+)$ {
metric avg_exp KEY=$1;
}
location /api/ {
api /status/http/metric_zones/avg_exp/metrics/;
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/set/100
$ curl 127.0.0.1/metric/set/200
$ curl 127.0.0.1/metric/set/0
$ curl 127.0.0.1/metric/set/8
$ curl 127.0.0.1/metric/set/30
```
Ожидаемое значение метрики в API:
```json
{
"KEY": 30.16
}
```
### average mean
Вычисляет среднее арифметическое. Принимает необязательные параметры
`window=` и `count=<число>`,
задающие соответственно интервал времени и объем выборки для усреднения.
По умолчанию: `window=off` (учитывается вся выборка) и `count=10`.
#### NOTE
Например, `window=5s` будет учитывать только события последних 5 секунд.
Параметрик `window` не может принимать значение `0`. Параметр
`count=число` управляет размером выборки (закэшированных значений)
для более плавного подсчета среднего.
Примеры:
```nginx
metric_zone avg_mean:1m average mean window=5s count=8;
# В качесте составной метрики:
#
# metric_complex_zone avg_mean:1m {
# some_metric_name average mean window=5s count=8;
# }
server {
listen 80;
location ~ ^/metric/set/(.+)$ {
metric avg_mean KEY=$1;
}
location /api/ {
api /status/http/metric_zones/avg_mean/metrics/;
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/set/0.1
$ curl 127.0.0.1/metric/set/0.1
$ curl 127.0.0.1/metric/set/0.4
$ curl 127.0.0.1/metric/set/10
$ curl 127.0.0.1/metric/set/1
$ curl 127.0.0.1/metric/set/1
```
Ожидаемое значение метрики в API:
```json
{
"KEY": 2.1
}
```
Если подождать 5 секунд, с момента последнего обновления метрики, то
ожидаемое значение метрики в API:
```json
{
"KEY": 0
}
```
### histogram
Создает набор "бакетов", увеличивая соответствующий счетчик,
если новое значение не превосходит порога бакета.
Формат параметров — список числовых порогов.
Полезен для анализа распределения, например времени ответа.
В качестве обязательных параметров передаются числа — предельные значения
бакетов, перечисленные в порядке возрастания.
#### NOTE
Значение бакета `inf` или `+Inf` можно использовать
для захвата всех значений, превышающих максимальный бакет.
Примеры:
```nginx
metric_zone hist:1m histogram 0.1 0.2 0.5 1 2 inf;
# В качесте составной метрики:
#
# metric_complex_zone hist:1m {
# some_metric_name histogram 0.1 0.2 0.5 1 2 inf;
# }
server {
listen 80;
location ~ ^/metric/set/(.+)$ {
metric histogram KEY=$1;
}
location /api/ {
api /status/http/metric_zones/hist/metrics/;
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/set/0.25
```
Ожидаемое значение метрики в API:
```json
{
"KEY": {
"0.1": 0,
"0.2": 0,
"0.5": 1,
"1": 1,
"2": 1,
"inf": 1
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/set/2
```
Ожидаемое значение метрики в API:
```json
{
"KEY": {
"0.1": 0,
"0.2": 0,
"0.5": 1,
"1": 1,
"2": 2,
"inf": 2
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/set/1000
```
Ожидаемое значение метрики в API:
```json
{
"KEY": {
"0.1": 0,
"0.2": 0,
"0.5": 1,
"1": 1,
"2": 2,
"inf": 3
}
}
```
## Встроенные переменные
Для каждой метрики создаются переменные:
- `$metric_`
- `$metric__key`
- `$metric__value`
Для составной метрики добавляется переменная:
- `$metric__value_`
### `$metric_`
Аналогично директиве [metric](#id5), можно использовать сеттер переменной
`$metric_` для подсчета метрики. Подсчет метрики будет происходить в фазе
[Rewrite](https://angie.software/angie/docs/configuration/modules/http/http_rewrite/),
что позволяет производить обработку метрики, например, из модуля
[njs](https://angie.software/angie/docs/configuration/modules/http/http_js/).
В качестве значения для установки переменной должна использоваться конструкция
`ключ=значение`. В качестве ключа и значения можно использовать текст,
переменные и их комбинации. Ключ — произвольная строка, по которой группируются значения.
Значение — число, обрабатываемое выбранным режимом.
Если пропущено, считается `0`.
Если параметр невозможно преобразовать в число, считается `1`.
Пример использования:
```nginx
http {
metric_zone counter:1m count;
# В этот момент добавилась переменная $metric_counter
server {
listen 80;
location /metric/ {
set $metric_counter $http_user_agent; # Вместо $http_user_agent=0
}
location /api/ {
allow 127.0.0.1;
deny all;
api /status/http/metric_zones/counter/;
}
}
}
```
Подсчет метрики с помощью модуля
[njs](https://angie.software/angie/docs/configuration/modules/http/http_js/):
```nginx
http {
js_import metrics.js;
resolver 127.0.0.53;
metric_complex_zone requests:1m {
min_time min;
max_time max;
total count;
}
location /metric/ {
js_content metrics.js_request;
js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
}
location /api/ {
allow 127.0.0.1;
deny all;
api /static/http/metric_zones/requests/;
}
}
```
Файл `metrics.js`:
```js
async function js_request(r) {
let start_time = Date.now();
let results = await Promise.all([ngx.fetch('https://google.com/'),
ngx.fetch('https://google.ru/')]);
// Используем сеттер переменной $metric_requests
r.variables.metric_requests = `google={Date.now() - start_time}`;
}
export default {js_request};
```
После нескольких запросов на `location /metric/` значения метрики могут быть
следующими:
```json
{
"discarded": 0,
"metrics": {
"google": {
"min_time": 70,
"max_time": 432,
"total": 6
}
}
}
```
#### NOTE
После установки переменной можно получить ее значение. Оно будет равно
указанной паре `ключ=значение`.
Также изменится значение, хранящееся в переменной `$metric__key`
на указанный ключ.
### `$metric__key` и `$metric__value`
Переменные `$metric__key` и `$metric__value` задают
соответственно ключ и значение. Обновление метрики происходит в момент установки
значения `$metric__value`, если ключ в `$metric__key`
уже задан.
#### NOTE
Для составной метрики значения подметрик в переменной `$metric__value`
объединены при помощи разделяющего символа `", "`.
Пример использования:
```nginx
http {
metric_zone gauge:1m gauge;
# В этот момент добавилась переменная $metric_gauge
# А еще переменные $metric_gauge_key и $metric_gauge_value
metric_complex_zone complex:1m {
hist histogram 1 2 3;
avg average exp;
}
# В этот момент добавилась переменная $metric_complex
# А еще переменные $metric_complex_key и $metric_complex_value
server {
listen 80;
location /gauge/ {
set $metric_gauge_key "foo";
set $metric_gauge_value 1;
# Либо set $metric_gauge foo=1;
return 200 "Updated with '$metric_gauge'\nValue='$metric_gauge_value'\n";
}
location /complex/ {
set $metric_complex_key "foo";
set $metric_complex_value 3;
# Либо set $metric_complex foo=3;
return 200 "Updated with '$metric_complex'\nValue='$metric_complex_value'\n";
}
}
}
```
Для такой конфигурации после запроса к `/gauge/` ожидается слудующий ответ:
```console
$ curl 127.0.0.1/gauge/
Updated with 'foo=1'
Value='1'
```
Для `/complex/`:
```console
$ curl 127.0.0.1/complex/
Updated with 'foo=3'
Value='0 0 1, 3'
```
#### NOTE
Если в качестве значения для переменной `$metric__value` указать
пустую строку, значение будет распознано как `0`. Если строка состоит из
символов, которые невозможно преобразовать в число,
она будет распознана как `1`.
Подсчет метрики произойдет только после того, как заданы значения переменных
`$metric__key` и `$metric__value`.
В таком случае значение, сохраненное в `$metric_`, станет равным
новой паре `ключ=значение`, указанной при помощи `$metric__key`
и `$metric__value`.
Значение, которое хранится в `$metric__key`, является последним
указанным через переменные ключом метрики.
Значение, которое хранится в `$metric__value`, является последним
подсчитанным значением метрики с ключом, установленным в `$metric__key`.
### `$metric__value_`
Для составной метрики значение конкретной подметрики можно получить при помощи
переменной `$metric__value_`, указав имя подметрики в качестве
.
Пример использования:
```nginx
http {
metric_complex_zone foo:1m {
count count;
min min;
avg average exp;
}
# В этот момент добавилась переменная $metric_foo
# А еще переменные $metric_foo_key и $metric_foo_value
# А так же $metric_foo_value_count, $metric_foo_value_min и $metric_foo_value_avg
server {
listen 80;
location /foo/ {
set $metric_foo_key bar;
set $metric_foo_value 9;
# Либо set $metric_foo bar=9;
return 200 "Updated with '$metric_foo'\nValues='$metric_foo_value'\nCount='$metric_foo_value_count'\n";
}
}
}
```
Для такой конфигурации после запроса к `/foo/` ожидается слудующий ответ:
```console
$ curl 127.0.0.1/foo/
Updated with 'bar=9'
Values='1, 9, 9'
Count='1'
```
## Дополнительные примеры
### Мониторинг HTTP-методов
```nginx
metric_zone http_methods:1m count;
server {
listen 80;
location / {
metric http_methods $request_method;
}
location /metrics/ {
allow 127.0.0.1;
deny all;
api /status/http/metric_zones/http_methods/metrics/;
}
}
```
Ответ:
```json
{
"GET": 65,
"POST": 20,
"PUT": 10,
"DELETE": 5
}
```
### Распределение времени ответа upstream
```nginx
metric_zone upstream_time:10m expire=on histogram
0.05 0.1 0.3 0.5 1 2 5 10 inf;
server {
listen 80;
location /backend/ {
proxy_pass http://backend;
metric upstream_time $upstream_addr=$upstream_response_time on=end;
}
location /metrics/ {
allow 127.0.0.1;
deny all;
api /status/http/metric_zones/upstream_time/;
}
}
```
Ответ:
```json
{
"discarded": 0,
"metrics": {
"backend1:8080": {
"0.05": 12,
"0.1": 28,
"0.3": 56,
"0.5": 78,
"1": 92,
"2": 97,
"5": 99,
"10": 100,
"inf": 100
}
}
}
```
### Активные подключения
```nginx
metric_zone active_connections:2m gauge;
server {
listen 80;
server_name site1.com;
location / {
# Увеличиваем при подключении
metric active_connections site1=1 on=request;
# Уменьшаем при завершении
metric active_connections site1=-1 on=end;
}
}
server {
listen 80;
server_name site2.com;
location / {
metric active_connections site2=1 on=request;
metric active_connections site2=-1 on=end;
}
}
server {
listen 8080;
location /connections/ {
allow 127.0.0.1;
deny all;
api /status/http/metric_zones/active_connections/metrics;
}
}
```
Ответ:
```json
{
"site1": 42,
"site2": 17
}
```
## Поддержка Prometheus
Angie имеет [встроенный модуль](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus) для отображения метрик в
[формате Prometheus](https://prometheus.io/docs/instrumenting/exposition_formats/),
поддерживающий произвольные метрики.
В качестве примера интеграции рассмотрим следующую конфигурацию:
```nginx
http {
# Создание метрики "upload"
metric_complex_zone upload:1m discard_key="other" {
stats histogram 64 256 1024 4096 16384 +Inf;
sum gauge;
count count;
avg_size average exp;
}
# Описание шаблона Prometheus для метрики "upload"
prometheus_template upload_metric {
'stats{le="$1"}' $p8s_value
path=~^/http/metric_zones/upload/metrics/angie/stats/(.+)$
type=histogram;
'stats_sum' $p8s_value
path=/http/metric_zones/upload/metrics/angie/sum;
'stats_count' $p8s_value
path=/http/metric_zones/upload/metrics/angie/count;
'avg_size' $p8s_value
path=/http/metric_zones/upload/metrics/angie/avg_size;
}
server {
listen 80;
# Обновление метрики
location ~ ^/upload/(.*)$ {
api /status/http/metric_zones/upload/metrics/angie/;
metric upload angie=$1 on=request;
}
# Таргет для сбора метрик
location /prometheus/upload_metric/ {
prometheus upload_metric;
}
}
}
```
После нескольких запросов на `/upload/...`:
```console
$ curl 127.0.0.1/upload/16384
$ curl 127.0.0.1/upload/64448
$ curl 127.0.0.1/upload/64
$ curl 127.0.0.1/upload/1028
$ curl 127.0.0.1/upload/1028
```
Значения метрики будут следующими:
```json
{
"stats": {
"64": 1,
"256": 1,
"1024": 1,
"4096": 3,
"16384": 4,
"+Inf": 5
},
"sum": 82952,
"count": 5,
"avg_size": 1077.9376
}
```
В [формате Prometheus](https://prometheus.io/docs/instrumenting/exposition_formats/)
метрика доступна на `/prometheus/upload_metric/`:
```text
# Angie Prometheus template "upload_metric"
# TYPE stats histogram
stats{le="64"} 1
stats{le="256"} 1
stats{le="1024"} 1
stats{le="4096"} 3
stats{le="16384"} 4
stats{le="+Inf"} 5
stats_sum 82952
stats_count 5
avg_size 1077.9376
```
# https://angie.software/angie/docs/configuration/modules/http/http_mirror.md
# Mirror
Позволяет зеркалировать исходный запрос при помощи создания фоновых зеркалирующих подзапросов. Ответы на зеркалирующие подзапросы игнорируются.
## Пример конфигурации
```nginx
location / {
mirror /mirror;
proxy_pass http://backend;
}
location = /mirror {
internal;
proxy_pass http://test_backend$request_uri;
}
```
## Директивы
### mirror
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `mirror` uri | `off`; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | `mirror off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает URI, на который будет зеркалироваться исходный запрос. На одном уровне конфигурации может быть задано несколько зеркал.
### mirror_request_body
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `mirror_request_body` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `mirror_request_body on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, зеркалировать ли тело запроса клиента. Если включено, то тело запроса клиента будет прочитано перед созданием зеркалирующих подзапросов. В этом случае небуферизованное проксирование тела запроса клиента, задаваемое директивами [proxy_request_buffering](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-request-buffering), [fastcgi_request_buffering](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-request-buffering), [scgi_request_buffering](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-request-buffering) и [uwsgi_request_buffering](https://angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-request-buffering), будет отключено.
```nginx
location / {
mirror /mirror;
mirror_request_body off;
proxy_pass http://backend;
}
location = /mirror {
internal;
proxy_pass http://log_backend;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
}
```
# https://angie.software/angie/docs/configuration/modules/http/http_mp4.md
# MP4
Обеспечивает серверную поддержку псевдо-стриминга для файлов в формате MP4.
Такие файлы обычно имеют расширения .mp4, .m4v и .m4a.
Псевдо-стриминг работает в паре с совместимым медиаплеером. Плеер посылает
серверу HTTP-запрос с указанием точки времени старта в аргументе start строки
запроса (время задается в секундах), а сервер в ответ посылает поток, у которого
начальная позиция соответствует запрошенному времени, например:
```none
http://example.com/elephants_dream.mp4?start=238.88
```
Это позволяет в любой момент времени выполнить произвольное позиционирование, а
также начать воспроизведение с середины временной шкалы.
В форматах, основанных на H.264, метаданные, необходимые для поддержки
позиционирования, хранятся в так называемом "moov-атоме". Это часть файла,
которая содержит индексную информацию для всего файла.
До начала воспроизведения плееру необходимо прочитать метаданные. Для этого он
отсылает специальный запрос с аргументом `start=0`. Многие кодирующие
программы добавляют метаданные в конец файла. Это неоптимально для
псевдо-стриминга, поскольку плееру потребуется загрузить файл целиком прежде чем
начать воспроизведение. Если метаданные находятся в начале файла, Angie
достаточно начать отправлять в ответ содержимое файла. Если же метаданные
находятся в конце файла, потребуется прочитать весь файл и подготовить новый
поток, в котором метаданные предшествуют медийным данным. Это требует
дополнительного процессорного времени, памяти и дискового ввода/вывода, поэтому
лучше заранее [подготовить](https://github.com/flowplayer/flowplayer/wiki/7.1.1-video-file-correction)
исходный файл для псевдо-стриминга, нежели делать это для каждого запроса.
Модуль также поддерживает аргумент `end` HTTP-запроса, задающий время
окончания воспроизведения потока. Аргумент `end` задается совместно с аргументом
`start` или самостоятельно:
```none
http://example.com/elephants_dream.mp4?start=238.88&end=555.55
```
Для запроса с ненулевыми аргументами `start` или `end` Angie
считывает из файла метаданные, готовит поток с запрошенным диапазоном и
отправляет его клиенту. Это тоже требует дополнительных ресурсов, как указано
выше.
Если аргумент `start` указывает на видеокадр, не являющийся ключевым, то
начало такого видео может воспроизводиться с ошибками. В этом случае к
запрашиваемому видео [могут](#mp4-start-key-frame) быть добавлены ближайший
к точке `start` ключевой кадр и все промежуточные кадры между ними. При
воспроизведении эти кадры будут скрыты при помощи edit-листа.
Если запрос, обрабатываемый этим модулем, не содержит аргументов `start` и
`end`, дополнительные ресурсы не тратятся, а файл отсылается
непосредственно как статический ресурс. Некоторые плееры также поддерживают
запросы с указанием диапазона запрашиваемых байт (byte-range requests), для них
этот модуль не требуется.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_mp4_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
#### WARNING
Если ранее использовался сторонний модуль `mp4`, следует его отключить.
Схожая поддержка псевдо-стриминга для FLV-файлов обеспечивается модулем [FLV](https://angie.software//angie/docs/configuration/modules/http/http_flv.md#http-flv).
## Пример конфигурации
```nginx
location /video/ {
mp4;
mp4_buffer_size 1m;
mp4_max_buffer_size 5m;
}
```
## Директивы
### mp4
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `mp4`; |
|------------------------------------------------------------------------------------------|----------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Включает в содержащем location обработку этим модулем.
### mp4_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `mp4_buffer_size` размер; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `mp4_buffer_size 512K;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает начальный размер буфера, используемого при обработке MP4-файлов.
### mp4_max_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `mp4_max_buffer_size` размер; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `mp4_max_buffer_size 10M;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
В ходе обработки метаданных может понадобиться буфер большего размера. Его размер не может превышать указанного, иначе Angie вернет серверную ошибку 500 (Internal Server Error) и запишет в лог следующее сообщение:
> "/some/movie/file.mp4" mp4 moov atom is too large:
> 12583268, you may want to increase mp4_max_buffer_size
### mp4_limit_rate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `mp4_limit_rate` `on` | `off` | коэффициент; |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| По умолчанию | `mp4_limit_rate off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает скорость передачи запрошенного MP4-файла клиенту.
Предельное значение вычисляется умножением заданного коэффициента
на средний битрейт файла.
- Специальное значение `off` отключает ограничение скорости.
- Специальное значение `on` соответствует коэффициенту `1.1`.
- Начало действия ограничения регулируется значением
[mp4_limit_rate_after](#mp4-limit-rate-after).
Запросы ограничиваются индивидуально:
если клиент открыл два соединения,
общая скорость удваивается.
В связи с этим обратите внимание на [limit_conn](https://angie.software//angie/docs/configuration/modules/http/http_api.md#limit-conn) и сопутствующие директивы.
### mp4_limit_rate_after
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `mp4_limit_rate_after` время; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `mp4_limit_rate_after 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает
(в пересчете на
[время воспроизведения](https://angie.software//angie/docs/configuration/configfile.md#syntax))
объем медиаданных,
после передачи которого
скорость будет ограничена директивой
[mp4_limit_rate](#mp4-limit-rate).
### mp4_start_key_frame
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `mp4_start_key_frame` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `mp4_start_key_frame off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Включает режим, в котором видео всегда начинается с ключевого видеокадра. Если аргумент start не указывает на ключевой кадр, то первоначальные кадры будут скрыты при помощи mp4 edit-листа. Edit-листы поддерживаются большинством плееров и браузеров включая Chrome, Safari, QuickTime и ffmpeg, частично поддерживаются в Firefox.
# https://angie.software/angie/docs/configuration/modules/http/http_perl.md
# Perl
Модуль позволяет писать обработчики location и переменных на Perl, а также вставлять вызовы Perl в SSI.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_perl_module`.
В наших репозиториях модуль собран [динамически](https://angie.software//angie/docs/installation/index.md#install-dynamicmodules) и
доступен отдельным пакетом `angie-module-perl` или `angie-pro-module-perl`;
подключить его можно с помощью директивы [load_module](https://angie.software//angie/docs/configuration/modules/core.md#load-module).
#### NOTE
Для сборки этого модуля необходим Perl версии 5.6.1 и выше. Компилятор C должен быть совместим с тем, которым был собран Perl.
## Известные проблемы
Модуль экспериментальный, поэтому возможно все.
Чтобы во время переконфигурации Perl перекомпилировал измененные модули, его нужно собрать с параметрами -Dusemultiplicity=yes или -Dusethreads=yes. Кроме того, чтобы во время работы Perl терял меньше памяти, его нужно собрать с параметром -Dusemymalloc=no. Узнать значения этих параметров у уже собранного Perl можно так (в примере приведены желаемые значения параметров):
```console
$ perl -V:usemultiplicity -V:usemymalloc
usemultiplicity='define';
usemymalloc='n';
```
Необходимо учитывать, что после пересборки Perl с новыми параметрами -Dusemultiplicity=yes или -Dusethreads=yes придется также пересобрать и все бинарные модули Perl, так как они просто перестанут работать с новым Perl.
Возможно, главный процесс, а вслед за ним и рабочие процессы, будут увеличиваться в размерах при каждой переконфигурации. Когда главный процесс вырастет до неприемлемых размеров, можно воспользоваться процедурой [обновления сервера на лету](https://angie.software//angie/docs/configuration/runtime.md#service-upgrade), не меняя при этом сам исполняемый файл.
Если модуль Perl выполняет длительную операцию, например, определяет адрес по имени, соединяется с другим сервером, делает запрос к базе данных, то на это время все остальные запросы, обслуживаемые данным рабочим процессом, не будут обрабатываться. Поэтому рекомендуется ограничиться операциями, время исполнения которых короткое и предсказуемое, например, обращение к локальной файловой системе.
## Пример конфигурации
```nginx
http {
perl_modules perl/lib;
perl_require hello.pm;
perl_set $msie6 '
sub {
my $r = shift;
my $ua = $r->header_in("User-Agent");
return "" if $ua =~ /Opera/;
return "1" if $ua =~ / MSIE [6-9]\.\d+/;
return "";
}
';
server {
location / {
perl hello::handler;
}
}
```
Модуль perl/lib/hello.pm:
```perl
package hello;
use nginx;
sub handler {
my $r = shift;
$r->send_http_header("text/html");
return OK if $r->header_only;
$r->print("hello!\n
");
if (-f $r->filename or -d _) {
$r->print($r->uri, " exists!\n");
}
return OK;
}
1;
__END__
```
## Директивы
### perl
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `perl` модуль :: функция | 'sub { ... }'; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location, limit_except |
Устанавливает обработчик Perl для данного location.
### perl_modules
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `perl_modules` путь; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает дополнительный путь для модулей Perl.
### perl_require
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `perl_require` модуль; |
|------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает имя модуля, который будет подгружаться при каждой переконфигурации. Директив perl_require может быть несколько.
### perl_set
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `perl_set` $переменная модуль :: функция | 'sub { ... }'; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Устанавливает обработчик Perl для указанной переменной.
## Вызов Perl из SSI
Формат команды SSI с вызовом Perl следующий:
```html
```
## Методы объекта запроса $r
### `$r->args`
возвращает аргументы запроса.
### `$r->filename`
возвращает имя файла, соответствующее URI запроса.
### `$r->has_request_body` (обработчик)
возвращает 0, если в запросе нет тела. Если же в запросе есть тело, то устанавливается указанный обработчик и возвращается 1. По окончании чтения тела запроса Angie вызовет установленный обработчик. Обратите внимание, что нужно передавать ссылку на функцию обработчика. Пример:
```perl
package hello;
use nginx;
sub handler {
my $r = shift;
if ($r->request_method ne "POST") {
return DECLINED;
}
if ($r->has_request_body(\&post)) {
return OK;
}
return HTTP_BAD_REQUEST;
}
sub post {
my $r = shift;
$r->send_http_header;
$r->print("request_body: \"", $r->request_body, "\"
");
$r->print("request_body_file: \"", $r->request_body_file, "\"
\n");
return OK;
}
1;
__END__
```
### `$r->allow_ranges`
разрешает использовать диапазоны байт (byte ranges) при передаче ответа.
### `$r->discard_request_body`
указывает Angie игнорировать тело запроса.
### `$r->header_in` (поле)
возвращает значение заданного поля в заголовке запроса клиента.
### `$r->header_only`
определяет, нужно ли передавать клиенту только заголовок ответа или весь ответ.
### `$r->header_out` (поле, значение)
устанавливает значение для заданного поля в заголовке ответа.
### `$r->internal_redirect` (uri)
делает внутреннее перенаправление на указанный uri. Перенаправление происходит уже после завершения обработчика Perl. Метод принимает экранированные URI и поддерживает перенаправления в [именованные location](https://angie.software//angie/docs/configuration/modules/http/index.md#named-location).
### `$r->log_error` (код_ошибки, сообщение)
записывает указанное сообщение в [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log). Если код_ошибки ненулевой, то к сообщению будет добавлен код ошибки и ее описание.
### `$r->print` (текст, ...)
метод передает клиенту данные.
### `$r->request_body`
возвращает тело запроса клиента при условии, что тело не записано во временный файл. Для того чтобы тело запроса клиента гарантированно находилось в памяти, нужно ограничить его размер с помощью [client_max_body_size](https://angie.software//angie/docs/configuration/modules/http/index.md#client-max-body-size) и задать достаточной размер для буфера [client_body_buffer_size](https://angie.software//angie/docs/configuration/modules/http/index.md#client-body-buffer-size).
### `$r->request_body_file`
возвращает имя файла, в котором хранится тело запроса клиента. По завершению обработки файл необходимо удалить. Для того чтобы тело запроса клиента всегда записывалось в файл, следует включить [client_body_in_file_only](https://angie.software//angie/docs/configuration/modules/http/index.md#client-body-in-file-only).
### `$r->request_method`
возвращает HTTP-метод запроса клиента.
### `$r->remote_addr`
возвращает IP-адрес клиента.
### `$r->flush`
немедленно передает данные клиенту.
### `$r->sendfile` (имя [, смещение [, длина ]])
передает клиенту содержимое указанного файла. Необязательные параметры задают начальное смещение и длину передаваемых данных. Непосредственно передача данных происходит уже после завершения обработчика Perl.
### `$r->send_http_header` ([тип])
передает клиенту заголовок ответа. Необязательный параметр тип устанавливает значение поля `Content-Type` в заголовке ответа. Пустая строка в качестве типа запрещает передачу поля `Content-Type` .
### `$r->status` (код)
устанавливает код ответа.
### `$r->sleep` (миллисекунды, обработчик)
устанавливает указанный обработчик и останавливает обработку запроса на заданное время. Angie в это время продолжает обрабатывать другие запросы. По истечении указанного времени Angie вызовет установленный обработчик. Обратите внимание, что нужно передавать ссылку на функцию обработчика. Для передачи данных между обработчиками следует использовать [$r‑>variable()](#p-r-variable). Пример:
```nginx
package hello;
use nginx;
sub handler {
my $r = shift;
$r->discard_request_body;
$r->variable("var", "OK");
$r->sleep(1000, \&next);
return OK;
}
sub next {
my $r = shift;
$r->send_http_header;
$r->print($r->variable("var"));
return OK;
}
1;
__END__
```
### `$r->unescape` (текст)
декодирует текст, заданный в виде "%XX".
### `$r->uri`
возвращает URI запроса.
### `$r->variable` (имя [, значение ])
возвращает или устанавливает значение указанной переменной. Переменные локальны для каждого запроса.
# https://angie.software/angie/docs/configuration/modules/http/http_prometheus.md
# Prometheus
Собирает [статистику](https://angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) Angie,
исходя из определенных в конфигурации шаблонов,
и возвращает сформированные на основании этих шаблонов метрики в
[формате Prometheus](https://prometheus.io/docs/instrumenting/exposition_formats/).
#### WARNING
Чтобы собирать статистику,
включите в нужных контекстах зону разделяемой памяти с помощью:
- директивы `zone` в [http_upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone)
или [stream_upstream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone);
- директивы [status_zone](https://angie.software//angie/docs/configuration/modules/http/index.md#status-zone);
- параметра `status_zone` в директиве [resolver](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver).
## Пример конфигурации
Три метрики для сбора статистики запросов к серверным зонам разделяемой памяти,
объединенные в шаблон `custom` и опубликованные по пути `/p8s`:
```nginx
http {
prometheus_template custom {
'angie_http_server_zones_requests_total{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/requests/total$
type=counter;
'angie_http_server_zones_requests_processing{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/requests/processing$
type=gauge;
'angie_http_server_zones_requests_discarded{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/requests/discarded$
type=counter;
}
# ...
server {
listen 80;
location =/p8s {
prometheus custom;
}
# ...
}
}
```
В состав Angie входит вспомогательный файл `prometheus_all.conf`,
куда включен набор общеупотребимых метрик, сведенных в шаблон `all`:
### Содержимое файла (Angie)
```nginx
prometheus_template all {
angie_connections_accepted $p8s_value
path=/connections/accepted
type=counter
'help=The total number of accepted client connections.';
angie_connections_dropped $p8s_value
path=/connections/dropped
type=counter
'help=The total number of dropped client connections.';
angie_connections_active $p8s_value
path=/connections/active
type=gauge
'help=The current number of active client connections.';
angie_connections_idle $p8s_value
path=/connections/idle
type=gauge
'help=The current number of idle client connections.';
'angie_slabs_pages_used{zone="$1"}' $p8s_value
path=~^/slabs/([^/]+)/pages/used$
type=gauge
'help=The number of currently used memory pages in a slab zone.';
'angie_slabs_pages_free{zone="$1"}' $p8s_value
path=~^/slabs/([^/]+)/pages/free$
type=gauge
'help=The number of currently free memory pages in a slab zone.';
'angie_slabs_pages_slots_used{zone="$1",size="$2"}' $p8s_value
path=~^/slabs/([^/]+)/slots/([^/]+)/used$
type=gauge
'help=The number of currently used memory slots of a specific size in a slab zone.';
'angie_slabs_pages_slots_free{zone="$1",size="$2"}' $p8s_value
path=~^/slabs/([^/]+)/slots/([^/]+)/free$
type=gauge
'help=The number of currently free memory slots of a specific size in a slab zone.';
'angie_slabs_pages_slots_reqs{zone="$1",size="$2"}' $p8s_value
path=~^/slabs/([^/]+)/slots/([^/]+)/reqs$
type=counter
'help=The total number of attempts to allocate a memory slot of a specific size in a slab zone.';
'angie_slabs_pages_slots_fails{zone="$1",size="$2"}' $p8s_value
path=~^/slabs/([^/]+)/slots/([^/]+)/fails$
type=counter
'help=The number of unsuccessful attempts to allocate a memory slot of a specific size in a slab zone.';
'angie_resolvers_queries{zone="$1",type="$2"}' $p8s_value
path=~^/resolvers/([^/]+)/queries/([^/]+)$
type=counter
'help=The number of queries of a specific type to resolve in a resolver zone.';
'angie_resolvers_sent{zone="$1",type="$2"}' $p8s_value
path=~^/resolvers/([^/]+)/sent/([^/]+)$
type=counter
'help=The number of sent DNS queries of a specific type to resolve in a resolver zone.';
'angie_resolvers_responses{zone="$1",status="$2"}' $p8s_value
path=~^/resolvers/([^/]+)/responses/([^/]+)$
type=counter
'help=The number of resolution results with a specific status in a resolver zone.';
'angie_http_server_zones_ssl_handshaked{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/ssl/handshaked$
type=counter
'help=The total number of successful SSL handshakes in an HTTP server zone.';
'angie_http_server_zones_ssl_reuses{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/ssl/reuses$
type=counter
'help=The total number of session reuses during SSL handshakes in an HTTP server zone.';
'angie_http_server_zones_ssl_timedout{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/ssl/timedout$
type=counter
'help=The total number of timed-out SSL handshakes in an HTTP server zone.';
'angie_http_server_zones_ssl_failed{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/ssl/failed$
type=counter
'help=The total number of failed SSL handshakes in an HTTP server zone.';
'angie_http_server_zones_requests_total{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/requests/total$
type=counter
'help=The total number of client requests received in an HTTP server zone.';
'angie_http_server_zones_requests_processing{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/requests/processing$
type=gauge
'help=The number of client requests currently being processed in an HTTP server zone.';
'angie_http_server_zones_requests_discarded{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/requests/discarded$
type=counter
'help=The total number of client requests completed in an HTTP server zone without sending a response.';
'angie_http_server_zones_responses{zone="$1",code="$2"}' $p8s_value
path=~^/http/server_zones/([^/]+)/responses/([^/]+)$
type=counter
'help=The number of responses with a specific status in an HTTP server zone.';
'angie_http_server_zones_data_received{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/data/received$
type=counter
'help=The total number of bytes received from clients in an HTTP server zone.';
'angie_http_server_zones_data_sent{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/data/sent$
type=counter
'help=The total number of bytes sent to clients in an HTTP server zone.';
'angie_http_location_zones_requests_total{zone="$1"}' $p8s_value
path=~^/http/location_zones/([^/]+)/requests/total$
type=counter
'help=The total number of client requests in an HTTP location zone.';
'angie_http_location_zones_requests_discarded{zone="$1"}' $p8s_value
path=~^/http/location_zones/([^/]+)/requests/discarded$
type=counter
'help=The total number of client requests completed in an HTTP location zone without sending a response.';
'angie_http_location_zones_responses{zone="$1",code="$2"}' $p8s_value
path=~^/http/location_zones/([^/]+)/responses/([^/]+)$
type=counter
'help=The number of responses with a specific status in an HTTP location zone.';
'angie_http_location_zones_data_received{zone="$1"}' $p8s_value
path=~^/http/location_zones/([^/]+)/data/received$
type=counter
'help=The total number of bytes received from clients in an HTTP location zone.';
'angie_http_location_zones_data_sent{zone="$1"}' $p8s_value
path=~^/http/location_zones/([^/]+)/data/sent$
type=counter
'help=The total number of bytes sent to clients in an HTTP location zone.';
'angie_http_upstreams_peers_state{upstream="$1",peer="$2"}' $p8st_all_ups_state
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/state$
type=gauge
'help=The current state of an upstream peer in "HTTP": 1 - up, 2 - down, 3 - unavailable, or 4 - recovering.';
'angie_http_upstreams_peers_selected_current{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/selected/current$
type=gauge
'help=The number of requests currently being processed by an upstream peer in "HTTP".';
'angie_http_upstreams_peers_selected_total{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/selected/total$
type=counter
'help=The total number of attempts to use an upstream peer in "HTTP".';
'angie_http_upstreams_peers_responses{upstream="$1",peer="$2",code="$3"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/responses/([^/]+)$
type=counter
'help=The number of responses with a specific status received from an upstream peer in "HTTP".';
'angie_http_upstreams_peers_data_sent{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/data/sent$
type=counter
'help=The total number of bytes sent to an upstream peer in "HTTP".';
'angie_http_upstreams_peers_data_received{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/data/received$
type=counter
'help=The total number of bytes received from an upstream peer in "HTTP".';
'angie_http_upstreams_peers_health_fails{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/fails$
type=counter
'help=The total number of unsuccessful attempts to communicate with an upstream peer in "HTTP".';
'angie_http_upstreams_peers_health_unavailable{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/unavailable$
type=counter
'help=The number of times when an upstream peer in "HTTP" became "unavailable" due to reaching the max_fails limit.';
'angie_http_upstreams_peers_health_downtime{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/downtime$
type=counter
'help=The total time (in milliseconds) that an upstream peer in "HTTP" was "unavailable".';
'angie_http_upstreams_keepalive{upstream="$1"}' $p8s_value
path=~^/http/upstreams/([^/]+)/keepalive$
type=gauge
'help=The number of currently cached keepalive connections for an HTTP upstream.';
'angie_http_caches_responses{zone="$1",status="$2"}' $p8s_value
path=~^/http/caches/([^/]+)/([^/]+)/responses$
type=counter
'help=The total number of responses processed in an HTTP cache zone with a specific cache status.';
'angie_http_caches_bytes{zone="$1",status="$2"}' $p8s_value
path=~^/http/caches/([^/]+)/([^/]+)/bytes$
type=counter
'help=The total number of bytes processed in an HTTP cache zone with a specific cache status.';
'angie_http_caches_responses_written{zone="$1",status="$2"}' $p8s_value
path=~^/http/caches/([^/]+)/([^/]+)/responses_written$
type=counter
'help=The total number of responses written to an HTTP cache zone with a specific cache status.';
'angie_http_caches_bytes_written{zone="$1",status="$2"}' $p8s_value
path=~^/http/caches/([^/]+)/([^/]+)/bytes_written$
type=counter
'help=The total number of bytes written to an HTTP cache zone with a specific cache status.';
'angie_http_caches_size{zone="$1"}' $p8s_value
path=~^/http/caches/([^/]+)/size$
type=gauge
'help=The current size (in bytes) of cached responses in an HTTP cache zone.';
'angie_http_caches_shards_size{zone="$1",path="$2"}' $p8s_value
path=~^/http/caches/([^/]+)/shards/([^/]+)/size$
type=gauge
'help=The current size (in bytes) of cached responses in a shard path of an HTTP cache zone.';
'angie_http_limit_conns{zone="$1",status="$2"}' $p8s_value
path=~^/http/limit_conns/([^/]+)/([^/]+)$
type=counter
'help=The number of requests processed by an HTTP limit_conn zone with a specific result.';
'angie_http_limit_reqs{zone="$1",status="$2"}' $p8s_value
path=~^/http/limit_reqs/([^/]+)/([^/]+)$
type=counter
'help=The number of requests processed by an HTTP limit_reqs zone with a specific result.';
'angie_stream_server_zones_ssl_handshaked{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/ssl/handshaked$
type=counter
'help=The total number of successful SSL handshakes in a stream server zone.';
'angie_stream_server_zones_ssl_reuses{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/ssl/reuses$
type=counter
'help=The total number of session reuses during SSL handshakes in a stream server zone.';
'angie_stream_server_zones_ssl_timedout{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/ssl/timedout$
type=counter
'help=The total number of timed-out SSL handshakes in a stream server zone.';
'angie_stream_server_zones_ssl_failed{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/ssl/failed$
type=counter
'help=The total number of failed SSL handshakes in a stream server zone.';
'angie_stream_server_zones_connections_total{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/connections/total$
type=counter
'help=The total number of client connections received in a stream server zone.';
'angie_stream_server_zones_connections_processing{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/connections/processing$
type=gauge
'help=The number of client connections currently being processed in a stream server zone.';
'angie_stream_server_zones_connections_discarded{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/connections/discarded$
type=counter
'help=The total number of client connections completed in a stream server zone without establishing a session.';
'angie_stream_server_zones_connections_passed{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/connections/passed$
type=counter
'help=The total number of client connections in a stream server zone passed for handling to a different listening socket.';
'angie_stream_server_zones_sessions{zone="$1",status="$2"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/sessions/([^/]+)$
type=counter
'help=The number of sessions finished with a specific status in a stream server zone.';
'angie_stream_server_zones_data_received{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/data/received$
type=counter
'help=The total number of bytes received from clients in a stream server zone.';
'angie_stream_server_zones_data_sent{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/data/sent$
type=counter
'help=The total number of bytes sent to clients in a stream server zone.';
'angie_stream_upstreams_peers_state{upstream="$1",peer="$2"}' $p8st_all_ups_state
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/state$
type=gauge
'help=The current state of an upstream peer in "stream": 1 - up, 2 - down, 3 - unavailable, or 4 - recovering.';
'angie_stream_upstreams_peers_selected_current{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/selected/current$
type=gauge
'help=The number of sessions currently being processed by an upstream peer in "stream".';
'angie_stream_upstreams_peers_selected_total{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/selected/total$
type=counter
'help=The total number of attempts to use an upstream peer in "stream".';
'angie_stream_upstreams_peers_data_sent{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/data/sent$
type=counter
'help=The total number of bytes sent to an upstream peer in "stream".';
'angie_stream_upstreams_peers_data_received{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/data/received$
type=counter
'help=The total number of bytes received from an upstream peer in "stream".';
'angie_stream_upstreams_peers_health_fails{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/fails$
type=counter
'help=The total number of unsuccessful attempts to communicate with an upstream peer in "stream".';
'angie_stream_upstreams_peers_health_unavailable{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/unavailable$
type=counter
'help=The number of times when an upstream peer in "stream" became "unavailable" due to reaching the max_fails limit.';
'angie_stream_upstreams_peers_health_downtime{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/downtime$
type=counter
'help=The total time (in milliseconds) that an upstream peer in "stream" was "unavailable".';
}
'angie_http_acme_clients_state{client="$1"}' $p8st_acme_cert_state
path=~^/http/acme_clients/([^/]+)/state$
type=gauge
'help=The current state of an ACME client: 1 - ready, 2 - requesting, 3 - disabled, or 4 - failed.';
'angie_http_acme_certs_state{client="$1"}' $p8st_acme_cli_state
path=~^/http/acme_clients/([^/]+)/certificate$
type=gauge
'help=The current state of an ACME client certificate: 1 - valid, 2 - mismatch, 3 - expired, 4 - missing, or 5 - error.';
map $p8s_value $p8st_all_ups_state {
volatile;
"up" 1;
"down" 2;
"unavailable" 3;
"recovering" 4;
# "unhealthy" 5;
# "checking" 6;
# "draining" 7;
"busy" 8;
default 0;
}
map $p8s_value $p8st_acme_cli_state {
volatile;
"ready" 1;
"requesting" 2;
"disabled" 3;
"failed" 4;
}
map $p8s_value $p8st_acme_cert_state {
volatile;
"valid" 1;
"mismatch" 2;
"expired" 3;
"missing" 4;
"error" 5;
}
```
### Содержимое файла (Angie PRO)
```nginx
prometheus_template all {
angie_connections_accepted $p8s_value
path=/connections/accepted
type=counter
'help=The total number of accepted client connections.';
angie_connections_dropped $p8s_value
path=/connections/dropped
type=counter
'help=The total number of dropped client connections.';
angie_connections_active $p8s_value
path=/connections/active
type=gauge
'help=The current number of active client connections.';
angie_connections_idle $p8s_value
path=/connections/idle
type=gauge
'help=The current number of idle client connections.';
'angie_slabs_pages_used{zone="$1"}' $p8s_value
path=~^/slabs/([^/]+)/pages/used$
type=gauge
'help=The number of currently used memory pages in a slab zone.';
'angie_slabs_pages_free{zone="$1"}' $p8s_value
path=~^/slabs/([^/]+)/pages/free$
type=gauge
'help=The number of currently free memory pages in a slab zone.';
'angie_slabs_pages_slots_used{zone="$1",size="$2"}' $p8s_value
path=~^/slabs/([^/]+)/slots/([^/]+)/used$
type=gauge
'help=The number of currently used memory slots of a specific size in a slab zone.';
'angie_slabs_pages_slots_free{zone="$1",size="$2"}' $p8s_value
path=~^/slabs/([^/]+)/slots/([^/]+)/free$
type=gauge
'help=The number of currently free memory slots of a specific size in a slab zone.';
'angie_slabs_pages_slots_reqs{zone="$1",size="$2"}' $p8s_value
path=~^/slabs/([^/]+)/slots/([^/]+)/reqs$
type=counter
'help=The total number of attempts to allocate a memory slot of a specific size in a slab zone.';
'angie_slabs_pages_slots_fails{zone="$1",size="$2"}' $p8s_value
path=~^/slabs/([^/]+)/slots/([^/]+)/fails$
type=counter
'help=The number of unsuccessful attempts to allocate a memory slot of a specific size in a slab zone.';
'angie_resolvers_queries{zone="$1",type="$2"}' $p8s_value
path=~^/resolvers/([^/]+)/queries/([^/]+)$
type=counter
'help=The number of queries of a specific type to resolve in a resolver zone.';
'angie_resolvers_sent{zone="$1",type="$2"}' $p8s_value
path=~^/resolvers/([^/]+)/sent/([^/]+)$
type=counter
'help=The number of sent DNS queries of a specific type to resolve in a resolver zone.';
'angie_resolvers_responses{zone="$1",status="$2"}' $p8s_value
path=~^/resolvers/([^/]+)/responses/([^/]+)$
type=counter
'help=The number of resolution results with a specific status in a resolver zone.';
'angie_http_server_zones_ssl_handshaked{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/ssl/handshaked$
type=counter
'help=The total number of successful SSL handshakes in an HTTP server zone.';
'angie_http_server_zones_ssl_reuses{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/ssl/reuses$
type=counter
'help=The total number of session reuses during SSL handshakes in an HTTP server zone.';
'angie_http_server_zones_ssl_timedout{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/ssl/timedout$
type=counter
'help=The total number of timed-out SSL handshakes in an HTTP server zone.';
'angie_http_server_zones_ssl_failed{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/ssl/failed$
type=counter
'help=The total number of failed SSL handshakes in an HTTP server zone.';
'angie_http_server_zones_requests_total{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/requests/total$
type=counter
'help=The total number of client requests received in an HTTP server zone.';
'angie_http_server_zones_requests_processing{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/requests/processing$
type=gauge
'help=The number of client requests currently being processed in an HTTP server zone.';
'angie_http_server_zones_requests_discarded{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/requests/discarded$
type=counter
'help=The total number of client requests completed in an HTTP server zone without sending a response.';
'angie_http_server_zones_responses{zone="$1",code="$2"}' $p8s_value
path=~^/http/server_zones/([^/]+)/responses/([^/]+)$
type=counter
'help=The number of responses with a specific status in an HTTP server zone.';
'angie_http_server_zones_data_received{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/data/received$
type=counter
'help=The total number of bytes received from clients in an HTTP server zone.';
'angie_http_server_zones_data_sent{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/data/sent$
type=counter
'help=The total number of bytes sent to clients in an HTTP server zone.';
'angie_http_location_zones_requests_total{zone="$1"}' $p8s_value
path=~^/http/location_zones/([^/]+)/requests/total$
type=counter
'help=The total number of client requests in an HTTP location zone.';
'angie_http_location_zones_requests_discarded{zone="$1"}' $p8s_value
path=~^/http/location_zones/([^/]+)/requests/discarded$
type=counter
'help=The total number of client requests completed in an HTTP location zone without sending a response.';
'angie_http_location_zones_responses{zone="$1",code="$2"}' $p8s_value
path=~^/http/location_zones/([^/]+)/responses/([^/]+)$
type=counter
'help=The number of responses with a specific status in an HTTP location zone.';
'angie_http_location_zones_data_received{zone="$1"}' $p8s_value
path=~^/http/location_zones/([^/]+)/data/received$
type=counter
'help=The total number of bytes received from clients in an HTTP location zone.';
'angie_http_location_zones_data_sent{zone="$1"}' $p8s_value
path=~^/http/location_zones/([^/]+)/data/sent$
type=counter
'help=The total number of bytes sent to clients in an HTTP location zone.';
'angie_http_upstreams_peers_backup{upstream="$1",peer="$2"}' $p8st_all_ups_backup
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/backup$
type=gauge
'help=The HTTP upstream peer backup group level.';
'angie_http_upstreams_peers_state{upstream="$1",peer="$2"}' $p8st_all_ups_state
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/state$
type=gauge
'help=The current state of an upstream peer in "HTTP": 1 - up, 2 - down, 3 - unavailable, 4 - recovering, 5 - unhealthy, 6 - checking, or 7 - draining.';
'angie_http_upstreams_peers_selected_current{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/selected/current$
type=gauge
'help=The number of requests currently being processed by an upstream peer in "HTTP".';
'angie_http_upstreams_peers_selected_total{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/selected/total$
type=counter
'help=The total number of attempts to use an upstream peer in "HTTP".';
'angie_http_upstreams_peers_responses{upstream="$1",peer="$2",code="$3"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/responses/([^/]+)$
type=counter
'help=The number of responses with a specific status received from an upstream peer in "HTTP".';
'angie_http_upstreams_peers_data_sent{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/data/sent$
type=counter
'help=The total number of bytes sent to an upstream peer in "HTTP".';
'angie_http_upstreams_peers_data_received{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/data/received$
type=counter
'help=The total number of bytes received from an upstream peer in "HTTP".';
'angie_http_upstreams_peers_health_fails{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/fails$
type=counter
'help=The total number of unsuccessful attempts to communicate with an upstream peer in "HTTP".';
'angie_http_upstreams_peers_health_unavailable{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/unavailable$
type=counter
'help=The number of times when an upstream peer in "HTTP" became "unavailable" due to reaching the max_fails limit.';
'angie_http_upstreams_peers_health_downtime{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/downtime$
type=counter
'help=The total time (in milliseconds) that an upstream peer in "HTTP" was "unavailable".';
'angie_http_upstreams_peers_health_header_time{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/header_time$
type=gauge
'help=Average time (in milliseconds) to receive the response headers from an upstream peer in "HTTP".';
'angie_http_upstreams_peers_health_response_time{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/response_time$
type=gauge
'help=Average time (in milliseconds) to receive the complete response from an upstream peer in "HTTP".';
'angie_http_upstreams_peers_health_probes_count{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/probes/count$
type=counter
'help=The total number of probes for this peer.';
'angie_http_upstreams_peers_health_probes_fails{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/probes/fails$
type=counter
'help=The total number of failed probes for this peer.';
'angie_http_upstreams_keepalive{upstream="$1"}' $p8s_value
path=~^/http/upstreams/([^/]+)/keepalive$
type=gauge
'help=The number of currently cached keepalive connections for an HTTP upstream.';
'angie_http_upstreams_backup_switch_active{upstream="$1"}' $p8s_value
path=~^/http/upstreams/([^/]+)/backup_switch/active$
type=gauge
'help=The currently active HTTP upstream servers backup group level.';
'angie_http_upstreams_queue_queued{upstream="$1"}' $p8s_value
path=~^/http/upstreams/([^/]+)/queue/queued$
type=counter
'help=The total number of queued requests for an HTTP upstream.';
'angie_http_upstreams_queue_waiting{upstream="$1"}' $p8s_value
path=~^/http/upstreams/([^/]+)/queue/waiting$
type=gauge
'help=The number of requests currently waiting in an HTTP upstream queue.';
'angie_http_upstreams_queue_dropped{upstream="$1"}' $p8s_value
path=~^/http/upstreams/([^/]+)/queue/dropped$
type=counter
'help=The total number of requests dropped from an HTTP upstream queue because the client had prematurely closed the connection.';
'angie_http_upstreams_queue_timedout{upstream="$1"}' $p8s_value
path=~^/http/upstreams/([^/]+)/queue/timedout$
type=counter
'help=The total number of requests timed out from an HTTP upstream queue.';
'angie_http_upstreams_queue_overflows{upstream="$1"}' $p8s_value
path=~^/http/upstreams/([^/]+)/queue/overflows$
type=counter
'help=The total number of requests rejected by an HTTP upstream queue because the size limit had been reached.';
'angie_http_caches_responses{zone="$1",status="$2"}' $p8s_value
path=~^/http/caches/([^/]+)/([^/]+)/responses$
type=counter
'help=The total number of responses processed in an HTTP cache zone with a specific cache status.';
'angie_http_caches_bytes{zone="$1",status="$2"}' $p8s_value
path=~^/http/caches/([^/]+)/([^/]+)/bytes$
type=counter
'help=The total number of bytes processed in an HTTP cache zone with a specific cache status.';
'angie_http_caches_responses_written{zone="$1",status="$2"}' $p8s_value
path=~^/http/caches/([^/]+)/([^/]+)/responses_written$
type=counter
'help=The total number of responses written to an HTTP cache zone with a specific cache status.';
'angie_http_caches_bytes_written{zone="$1",status="$2"}' $p8s_value
path=~^/http/caches/([^/]+)/([^/]+)/bytes_written$
type=counter
'help=The total number of bytes written to an HTTP cache zone with a specific cache status.';
'angie_http_caches_size{zone="$1"}' $p8s_value
path=~^/http/caches/([^/]+)/size$
type=gauge
'help=The current size (in bytes) of cached responses in an HTTP cache zone.';
'angie_http_caches_shards_size{zone="$1",path="$2"}' $p8s_value
path=~^/http/caches/([^/]+)/shards/([^/]+)/size$
type=gauge
'help=The current size (in bytes) of cached responses in a shard path of an HTTP cache zone.';
'angie_http_limit_conns{zone="$1",status="$2"}' $p8s_value
path=~^/http/limit_conns/([^/]+)/([^/]+)$
type=counter
'help=The number of requests processed by an HTTP limit_conn zone with a specific result.';
'angie_http_limit_reqs{zone="$1",status="$2"}' $p8s_value
path=~^/http/limit_reqs/([^/]+)/([^/]+)$
type=counter
'help=The number of requests processed by an HTTP limit_reqs zone with a specific result.';
'angie_stream_server_zones_ssl_handshaked{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/ssl/handshaked$
type=counter
'help=The total number of successful SSL handshakes in a stream server zone.';
'angie_stream_server_zones_ssl_reuses{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/ssl/reuses$
type=counter
'help=The total number of session reuses during SSL handshakes in a stream server zone.';
'angie_stream_server_zones_ssl_timedout{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/ssl/timedout$
type=counter
'help=The total number of timed-out SSL handshakes in a stream server zone.';
'angie_stream_server_zones_ssl_failed{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/ssl/failed$
type=counter
'help=The total number of failed SSL handshakes in a stream server zone.';
'angie_stream_server_zones_connections_total{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/connections/total$
type=counter
'help=The total number of client connections received in a stream server zone.';
'angie_stream_server_zones_connections_processing{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/connections/processing$
type=gauge
'help=The number of client connections currently being processed in a stream server zone.';
'angie_stream_server_zones_connections_discarded{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/connections/discarded$
type=counter
'help=The total number of client connections completed in a stream server zone without establishing a session.';
'angie_stream_server_zones_connections_passed{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/connections/passed$
type=counter
'help=The total number of client connections in a stream server zone passed for handling to a different listening socket.';
'angie_stream_server_zones_sessions{zone="$1",status="$2"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/sessions/([^/]+)$
type=counter
'help=The number of sessions finished with a specific status in a stream server zone.';
'angie_stream_server_zones_data_received{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/data/received$
type=counter
'help=The total number of bytes received from clients in a stream server zone.';
'angie_stream_server_zones_data_sent{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/data/sent$
type=counter
'help=The total number of bytes sent to clients in a stream server zone.';
'angie_stream_upstreams_peers_backup{upstream="$1",peer="$2"}' $p8st_all_ups_backup
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/backup$
type=gauge
'help=The "stream" upstream peer backup group level.';
'angie_stream_upstreams_peers_state{upstream="$1",peer="$2"}' $p8st_all_ups_state
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/state$
type=gauge
'help=The current state of an upstream peer in "stream": 1 - up, 2 - down, 3 - unavailable, 4 - recovering, 5 - unhealthy, 6 - checking, or 7 - draining.';
'angie_stream_upstreams_peers_selected_current{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/selected/current$
type=gauge
'help=The number of sessions currently being processed by an upstream peer in "stream".';
'angie_stream_upstreams_peers_selected_total{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/selected/total$
type=counter
'help=The total number of attempts to use an upstream peer in "stream".';
'angie_stream_upstreams_peers_data_sent{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/data/sent$
type=counter
'help=The total number of bytes sent to an upstream peer in "stream".';
'angie_stream_upstreams_peers_data_received{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/data/received$
type=counter
'help=The total number of bytes received from an upstream peer in "stream".';
'angie_stream_upstreams_peers_data_pkt_sent{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/data/pkt_sent$
type=counter
'help=The total number of packets sent to an upstream peer in "stream".';
'angie_stream_upstreams_peers_data_pkt_received{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/data/pkt_received$
type=counter
'help=The total number of packets received from an upstream peer in "stream".';
'angie_stream_upstreams_peers_health_fails{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/fails$
type=counter
'help=The total number of unsuccessful attempts to communicate with an upstream peer in "stream".';
'angie_stream_upstreams_peers_health_unavailable{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/unavailable$
type=counter
'help=The number of times when an upstream peer in "stream" became "unavailable" due to reaching the max_fails limit.';
'angie_stream_upstreams_peers_health_downtime{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/downtime$
type=counter
'help=The total time (in milliseconds) that an upstream peer in "stream" was "unavailable".';
'angie_stream_upstreams_peers_health_connect_time{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/connect_time$
type=gauge
'help=Average time (in milliseconds) to connect to an upstream peer in "stream".';
'angie_stream_upstreams_peers_health_first_byte_time{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/first_byte_time$
type=gauge
'help=Average time (in milliseconds) to receive the first byte from an upstream peer in "stream".';
'angie_stream_upstreams_peers_health_last_byte_time{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/last_byte_time$
type=gauge
'help=Average time (in milliseconds) of the whole communication session with an upstream peer in "stream".';
'angie_stream_upstreams_peers_health_probes_count{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/probes/count$
type=counter
'help=The total number of probes for this peer.';
'angie_stream_upstreams_peers_health_probes_fails{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/probes/fails$
type=counter
'help=The total number of failed probes for this peer.';
'angie_stream_upstreams_backup_switch_active{upstream="$1"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/backup_switch/active$
type=gauge
'help=The currently active "stream" upstream servers backup group level.';
}
'angie_http_acme_clients_state{client="$1"}' $p8st_acme_cert_state
path=~^/http/acme_clients/([^/]+)/state$
type=gauge
'help=The current state of an ACME client: 1 - ready, 2 - requesting, 3 - disabled, or 4 - failed.';
'angie_http_acme_certs_state{client="$1"}' $p8st_acme_cli_state
path=~^/http/acme_clients/([^/]+)/certificate$
type=gauge
'help=The current state of an ACME client certificate: 1 - valid, 2 - mismatch, 3 - expired, 4 - missing, or 5 - error.';
map $p8s_value $p8st_all_ups_state {
volatile;
"up" 1;
"down" 2;
"unavailable" 3;
"recovering" 4;
"unhealthy" 5;
"checking" 6;
"draining" 7;
"busy" 8;
default 0;
}
map $p8s_value $p8st_acme_cli_state {
volatile;
"ready" 1;
"requesting" 2;
"disabled" 3;
"failed" 4;
}
map $p8s_value $p8st_acme_cert_state {
volatile;
"valid" 1;
"mismatch" 2;
"expired" 3;
"missing" 4;
"error" 5;
}
map $p8s_value $p8st_all_ups_backup {
volatile;
"false" 0;
"true" 1;
default $p8s_value;
}
```
Его использование:
```nginx
http {
include prometheus_all.conf;
# ...
server {
listen 80;
location =/p8s {
prometheus all;
}
# ...
}
}
```
```console
$ curl localhost/p8s
# Angie Prometheus template "all"
...
```
## Директивы
### prometheus
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `prometheus` имя_шаблона; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Указывает для контекста `location` шаблон-обработчик,
заданный директивой [prometheus_template](#prometheus-template).
При запросе этот `location` вычисляет и возвращает метрики шаблона
в формате Prometheus.
```nginx
location =/p8s {
prometheus custom;
}
```
```console
$ curl localhost/p8s
# Angie Prometheus template "custom"
...
```
### prometheus_template
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `prometheus_template` имя_шаблона { ... } |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Определяет именованный шаблон метрик, собираемых и экспортируемых Angie,
для использования с директивой [prometheus](#id3).
#### NOTE
В состав Angie также входит готовый шаблон [all](#prometheus-all),
куда включен набор наиболее общеупотребимых метрик.
Может содержать произвольное число определений метрик,
каждая из которых имеет следующую структуру:
<имя_метрики> <переменная> [`path=`<строка_сопоставления>] [`type=`<тип>] [`help=`<справка>].
| `имя_метрики` | Задает имя метрики,
под которым она будет добавлена в формате Prometheus в ответ на запрос.
Может содержать необязательную часть с метками (` *...*`), например:
```none
http_requests_total{method="$1",code="$2"}
```
В значениях меток можно использовать переменные Angie;
если строка_сопоставления задана регулярным выражением,
то можно также использовать определенные в этом выражении группы захвата.
Такие переменные и группы вычисляются при получении значения метрики,
которое задает переменная. |
|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `переменная` | Задает имя переменной, которая будет вычислена и добавлена
как значение метрики в ответ на запрос.
Если переменной нет или результат вычисления пуст (`""`),
метрика не добавляется. |
Метрика вычисляется со значением, которое задает переменная;
при успехе вычисления метрика добавляется в ответ, например:
```nginx
'angie_time{version="$angie_version"}' $msec;
```
```console
$ curl localhost/p8s
angie_time{version="|version|"} 1695119820.562
```
| `path=строка_сопоставления` | Сопоставляется со всеми конечными путями метрик в поддереве
[/status](https://angie.software//angie/docs/configuration/modules/http/http_api.md#metrics)
API-интерфейса Angie,
позволяя добавить в ответ сразу несколько экземпляров метрики. |
|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
При сопоставлении пути берутся с начальной косой чертой, но без конечной,
например `/angie/generation`; при этом регистр символов не учитывается.
Есть два способа сопоставления:
| `path=точное_соответствие` | Проверяется посимвольным сравнением. |
|------------------------------|------------------------------------------------------------------------------------------------------------------------|
| `path=~регулярное_выражение` | Проверяется при помощи библиотеки PCRE; может задавать группы захвата
для использования в метках поля имя метрики. |
Если строка_сопоставления соответствует какому-либо пути,
то значение метрики Angie по нему заносится в переменную
[$p8s_value](#v-p8s-value),
которую при заданном `path=` можно использовать в поле переменная.
Если строка_сопоставления заканчивается конечной косой чертой, значением
метрики будет количество элементов соответствующего списка или объекта.
Например:
```nginx
'angie_http_server_zones_count' $p8s_value
path=/http/server_zones/;
```
В случае регулярного выражения совпадающих путей может быть несколько;
метрика добавляется в ответ для *каждого* совпадения.
В сочетании с группами захвата это позволяет получить ряд метрик
с одним именем и разными метками, например:
```nginx
'angie_slabs_slots_free{zone="$1",size="$2"}' $p8s_value
path=~^/slabs/([^/]+)/slots/([^/]+)/free$;
```
Это определение добавляет метрики для всех зон и всех размеров,
которые есть сейчас в конфигурации:
```none
angie_slabs_slots_free{zone="one",size="8"} 502
angie_slabs_slots_free{zone="one",size="16"} 249
angie_slabs_slots_free{zone="one",size="32"} 122
angie_slabs_slots_free{zone="one",size="128"} 22
angie_slabs_slots_free{zone="one",size="512"} 4
angie_slabs_slots_free{zone="two",size="8"} 311
...
```
Если совпадений нет (при любом способе сопоставления),
то метрика не добавляется.
#### NOTE
Параметр `path=` доступен только
при сборке Angie с модулем [API](https://angie.software//angie/docs/configuration/modules/http/http_api.md#http-api).
| `type=тип`, `help=справка` | Задают соответственно тип и справочную строку метрики в
[формате Prometheus](https://prometheus.io/docs/instrumenting/exposition_formats/#comments-help-text-and-type-information),
которые добавляются с ней в ответ без изменений и проверок. |
|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
## Встроенные переменные
В модуле `http_prometheus` есть встроенная переменная,
получающая значение при сопоставлении путей метрик из раздела
[/status](https://angie.software//angie/docs/configuration/modules/http/http_api.md#metrics)
API-интерфейса Angie
с параметром строка_сопоставления метрик, заданных директивой
[prometheus_template](#prometheus-template).
### `$p8s_value`
Если строка_сопоставления метрики, заданной в [prometheus_template](#prometheus-template),
соответствует какому-либо пути,
то значение метрики Angie, находящееся по этому пути,
заносится в переменную `$p8s_value`.
Она предназначена для использования в поле переменная в определениях метрик,
которые вычисляются на основе параметра `path=`.
Значения метрик Angie, заносимые в переменную `$p8s_value`,
не всегда отвечают потребностям формата Prometheus.
Тогда можно воспользоваться директивой [map](https://angie.software//angie/docs/configuration/modules/http/http_map.md#id3),
например для преобразования строк в числа:
```nginx
map $p8s_value $ups_state_n {
up 0;
unavailable 1;
down 2;
default 3;
}
prometheus_template main {
'angie_http_upstreams_state{upstream="$1",peer="$2"}' $ups_state_n
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/state$;
}
```
Если у метрики Angie логическое значение, то есть `true` или `false`,
переменная получает значение `"1"` или `"0"` соответственно;
если значение метрики — `null`, то переменная будет равна `"(null)"`.
Для дат используется целочисленный формат эпохи UNIX.
# https://angie.software/angie/docs/configuration/modules/http/http_proxy.md
# Proxy
Позволяет передавать запросы другому (проксируемому) серверу.
## Пример конфигурации
```nginx
location / {
proxy_pass http://localhost:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_cache cache_zone;
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
}
```
## Директивы
### proxy_bind
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_bind` адрес [`transparent`] | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает локальный IP-адрес с необязательным портом, который будет использоваться в исходящих соединениях с проксируемым сервером. В значении параметра допустимо использование переменных. Специальное значение `off` отменяет действие унаследованной с предыдущего уровня конфигурации директивы proxy_bind, позволяя системе самостоятельно выбирать локальный IP-адрес и порт.
Параметр `transparent` позволяет задать нелокальный IP-aдрес, который будет использоваться в исходящих соединениях с проксируемым сервером, например, реальный IP-адрес клиента:
```nginx
proxy_bind $remote_addr transparent;
```
Для работы параметра обычно требуется запустить рабочие процессы Angie с привилегиями [суперпользователя](https://angie.software//angie/docs/configuration/modules/core.md#user). В Linux это не требуется, так как если указан параметр transparent, то рабочие процессы наследуют capability CAP_NET_RAW из главного процесса.
#### NOTE
Необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с проксируемого сервера.
### proxy_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_buffer_size` размер; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `proxy_buffer_size 4k|8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает размер буфера, в который будет читаться первая часть ответа, получаемого от проксируемого сервера. В этой части ответа обычно находится небольшой заголовок ответа. По умолчанию размер одного буфера равен размеру страницы памяти. В зависимости от платформы это или 4K, или 8K, однако его можно сделать меньше.
### proxy_buffering
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_buffering` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `proxy_buffering on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает буферизацию ответов от проксируемого сервера.
| `on` | Angie принимает ответ проксируемого сервера как можно быстрее, сохраняя
его в буферы, заданные директивами [proxy_buffer_size](#proxy-buffer-size) и
[proxy_buffers](#proxy-buffers). Отправка клиенту при этом выполняется
параллельно: заполненные буферы передаются на отправку (никто их не
удерживает), но суммарно не более значения
[proxy_busy_buffers_size](#proxy-busy-buffers-size). Если буфер заполнен не полностью, то на
отправку он не передается, если только это не последние данные ответа.
Поэтому для моментальной передачи каждых нескольких байт режим
буферизированного чтения не подходит. Если ответ не вмещается целиком в
память, то его часть может быть записана на диск во [временный файл](#proxy-temp-path). Запись во временные файлы контролируется директивами
[proxy_max_temp_file_size](#proxy-max-temp-file-size) и [proxy_temp_file_write_size](#proxy-temp-file-write-size). |
|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | Ответ передается клиенту сразу же по мере его поступления. Angie работает
в цикле "чтение — отправка" и не ждет, пока буфер заполнится целиком:
например, прочитанные 10 байт из буфера 4К будут сразу отправлены
клиенту. При этом, если весь ответ умещается в буфер, Angie может
прочитать его целиком. Максимальный размер данных, который Angie может
принять от сервера за один раз, задается директивой
[proxy_buffer_size](#proxy-buffer-size). В режиме `off` Angie не кэширует ответы и
не работает [proxy_limit_rate](#proxy-limit-rate). |
Буферизация может быть также включена или выключена путем передачи значения
"yes" или "no" в поле `X-Accel-Buffering` заголовка ответа. Эту
возможность можно запретить с помощью директивы
[proxy_ignore_headers](#proxy-ignore-headers).
### proxy_buffers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_buffers` число размер; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `proxy_buffers 8 4k | 8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число и размер буферов для одного соединения, в которые будет читаться ответ, получаемый от проксируемого сервера.
По умолчанию размер одного буфера равен размеру страницы. В зависимости от платформы это или 4K, или 8K.
### proxy_busy_buffers_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_busy_buffers_size` размер; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `proxy_busy_buffers_size 8k | 16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
При включенной [буферизации](#proxy-buffering) ответов проксируемого сервера, ограничивает суммарный размер буферов, которые могут быть заняты для отправки ответа клиенту, пока ответ еще не прочитан целиком. Оставшиеся буферы тем временем могут использоваться для чтения ответа и, при необходимости, буферизации части ответа во временный файл.
По умолчанию размер ограничен величиной двух буферов, заданных директивами [proxy_buffer_size](#proxy-buffer-size) и [proxy_buffers](#proxy-buffers).
### proxy_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache` зона | `off` [`path=`путь]; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | `proxy_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает зону разделяемой памяти для кэширования.
Одну и ту же зону можно использовать в нескольких местах конфигурации.
В значении параметра допускаются переменные.
| `off` | запрещает кэширование, унаследованное с предыдущего уровня конфигурации. |
|---------|----------------------------------------------------------------------------|
В Angie PRO можно указать несколько директив [proxy_cache_path](#proxy-cache-path),
использующих одно и то же значение `keys_zone`, чтобы включить шардинг
кэша. При этом следует задать параметр `path` директивы
[proxy_cache](#proxy-cache), использующей это значение `keys_zone`:
| `path=`путь | Значение вычисляется в момент *кэширования* ответа от бэкенда
и предполагает использование переменных, в том числе содержащих
информацию из ответа.
Если ответ берется из кэша, то путь не вычисляется заново;
таким образом, кэшированный ответ сохраняет изначальный путь,
пока не будет удален из кэша. |
|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
Это позволяет выбирать нужный путь кэша, применяя директивы [map](https://angie.software//angie/docs/configuration/modules/http/http_map.md#id3) или
скрипты к ответам от бэкенда. Пример для `Content-Type`:
```nginx
proxy_cache_path /cache/one keys_zone=zone:10m;
proxy_cache_path /cache/two keys_zone=zone;
map $upstream_http_content_type $cache {
~^text/ one;
default two;
}
server {
...
location / {
proxy_pass http://backend;
proxy_cache zone path=/cache/$cache;
proxy_cache_valid 200 10m;
}
}
```
Здесь есть два пути кэша и отображение переменной, чтобы их различать.
Если `Content-Type` начинается с `text/`, будет выбран первый путь,
иначе — второй.
#### NOTE
При использовании [proxy_cache](#proxy-cache)
обычно необходимо также задать директиву [proxy_cache_valid](#proxy-cache-valid),
чтобы явно указать время действия кэшированных ответов.
Если она не задана, Angie не использует значения по умолчанию,
а определяет время хранения ответа в кэше
на основе HTTP-заголовков ответа от сервера в следующем порядке приоритета:
1. Заголовок `X-Accel-Expires` (наивысший приоритет).
2. Заголовок `Cache-Control`
с параметрами `max-age` или `s-maxage`.
3. Заголовок `Expires`.
Если ни один заголовок не содержит допустимого значения или их нет вовсе,
ответ не будет кэшироваться, так как определить срок его действия нельзя.
### proxy_cache_background_update
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_background_update` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| По умолчанию | `proxy_cache_background_update off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запустить фоновый подзапрос для обновления просроченного элемента кэша, в то время как клиенту возвращается устаревший кэшированный ответ.
#### WARNING
Использование устаревшего кэшированного ответа в момент его обновления должно быть [разрешено](#proxy-cache-use-stale-updating).
### proxy_cache_bypass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_bypass` ...; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает условия, при которых ответ не будет браться из кэша. Если значение хотя бы одного из строковых параметров непустое и не равно "0", то ответ не берется из кэша:
```nginx
proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
proxy_cache_bypass $http_pragma $http_authorization;
```
Можно использовать совместно с директивой [proxy_no_cache](#proxy-no-cache).
### proxy_cache_convert_head
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_convert_head` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `proxy_cache_convert_head on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает преобразование метода "HEAD" в "GET" для кэширования. Если преобразование выключено, то необходимо, чтобы [ключ кэширования](#proxy-cache-key) включал в себя [$request_method](https://angie.software//angie/docs/configuration/modules/http/index.md#v-request-method).
### proxy_cache_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_key` строка; |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| По умолчанию | `proxy_cache_key $scheme$proxy_host$request_uri;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает ключ для кэширования, например,
```nginx
proxy_cache_key "$host$request_uri $cookie_user";
```
По умолчанию значение директивы близко к строке
```nginx
proxy_cache_key $scheme$proxy_host$uri$is_args$args;
```
### proxy_cache_lock
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_lock` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `proxy_cache_lock off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если включено, одновременно только одному запросу будет позволено заполнить новый элемент кэша, идентифицируемый согласно директиве [proxy_cache_key](#proxy-cache-key), передав запрос на проксируемый сервер. Остальные запросы этого же элемента будут либо ожидать появления ответа в кэше, либо освобождения блокировки этого элемента, в течение времени, заданного директивой [proxy_cache_lock_timeout](#proxy-cache-lock-timeout).
### proxy_cache_lock_age
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_lock_age` время; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `proxy_cache_lock_age 5s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если последний запрос, переданный на проксируемый сервер для заполнения нового элемента кэша, не завершился за указанное время, на проксируемый сервер может быть передан еще один запрос.
### proxy_cache_lock_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_lock_timeout` время; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `proxy_cache_lock_timeout 5s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут для [proxy_cache_lock](#proxy-cache-lock). По истечении указанного времени запрос будет передан на проксируемый сервер, однако ответ не будет кэширован.
### proxy_cache_max_range_offset
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_max_range_offset` число; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает смещение в байтах для запросов с указанием диапазона запрашиваемых байт (byte-range requests). Если диапазон находится за указанным смещением, range-запрос будет передан на проксируемый сервер и ответ не будет кэширован.
### proxy_cache_methods
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_methods` `GET` | `HEAD` | `POST` ...; |
|------------------------------------------------------------------------------------------|------------------------------------------------------|
| По умолчанию | `proxy_cache_methods GET HEAD;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если метод запроса клиента указан в этой директиве, то ответ будет кэширован. Методы "GET" и "HEAD" всегда добавляются в список, но тем не менее рекомендуется перечислять их явно. См. также директиву [proxy_no_cache](#proxy-no-cache).
### proxy_cache_min_uses
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_min_uses` число; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `proxy_cache_min_uses 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число запросов, после которого ответ будет кэширован.
#### WARNING
Метаданные кэша хранятся в разделяемой памяти. Ручное удаление файлов кэша не
сбрасывает счетчики и может привести к непредсказуемому поведению. Для
полного сброса остановите сервер, удалите директорию кэша и запустите снова.
#### NOTE
Сторонние модули очистки кэша (например, [Cache Purge](https://angie.software//angie/docs/installation/external-modules/cache-purge.md#external-cache-purge)) удаляют только
файлы, но не сбрасывают счетчик proxy_cache_min_uses. Директива
предназначена для защиты кэша от загрязнения редкими запросами, и сброс
счетчика при очистке может негативно повлиять на производительность.
### proxy_cache_path
#### Versionchanged
Изменено в версии 1.9.0.
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_path` путь [`levels=`уровни] [`use_temp_path=``on` | `off`] `keys_zone=`имя:размер[:`file=`файл] [`inactive=`время] [`max_size=`размер] [`min_free=`размер] [`manager_files=`число] [`manager_sleep=`время] [`manager_threshold=`время] [`loader_files=`число] [`loader_sleep=`время] [`loader_threshold=`время]; |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает путь и другие параметры кэша. Данные кэша хранятся в файлах. Именем файла в кэше является результат функции MD5 от [ключа кэширования](#proxy-cache-key).
| `levels` | задает уровни иерархии кэша: можно задать от 1 до 3 уровней, на каждом уровне допускаются значения 1 или 2. |
|------------|---------------------------------------------------------------------------------------------------------------|
Например, при использовании
```nginx
proxy_cache_path /data/angie/cache levels=1:2 keys_zone=one:10m;
```
имена файлов в кэше будут такого вида:
```nginx
/data/angie/cache/c/29/b7f54b2df7773722d382f4809d65029c
```
Кэшируемый ответ сначала записывается во временный файл, а потом этот файл переименовывается. Временные файлы и кэш могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешевой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если кэш будет находиться на той же файловой системе, что и каталог с временными файлами.
| `use_temp_path=on` | `off` | определяет каталог, который будет использоваться для временных файлов |
|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `on` | Если параметр не задан или установлен в значение `on`, будет использоваться каталог, задаваемый директивой [proxy_temp_path](#proxy-temp-path) для данного location |
| `off` | временные файлы будут располагаться непосредственно в каталоге кэша |
| `keys_zone` | Задает имя и размер зоны разделяемой памяти для хранения всех активных ключей и информации о данных. Метаданные кэша хранятся в разделяемой памяти.
Зоны размером в 1 мегабайт достаточно для хранения около 8000 ключей.
Когда с `keys_zone` задан необязательный файл,
Angie сбрасывает содержимое этой зоны на диск
при завершении работы основного процесса
и пытается восстановить ее по тому же адресу памяти
при следующем [запуске](https://angie.software//angie/docs/configuration/runtime.md#runtime)
или после [обновления бинарных файлов](https://angie.software//angie/docs/configuration/runtime.md#service-upgrade),
чтобы обеспечить более надежную сохраняемость данных
и сократить время загрузки кэша.
Если восстановление области невозможно из-за изменения ее размера,
несовместимости версий бинарных файлов или по другим причинам,
Angie запишет в журнал предупреждение (`failed to restore zone at address`)
и не будет использовать механизм восстановления зоны.
Вместо этого несовместимый файл будет переименован в `.old`;
вы можете либо удалить его,
либо восстановить его имя и вернуть Angie к конфигурации и версии,
в которых этот файл был изначально создан.
#### WARNING
Убедитесь, что путь к файлу указан правильно
и имеет необходимые права доступа для использования Angie,
а также защищен от несанкционированного доступа;
относительные пути основаны на [префиксе](https://angie.software//angie/docs/installation/sourcebuild.md#paths). |
| `inactive` | Если к данным кэша не обращаются в течение времени, заданного этим параметром, то данные удаляются, независимо от их свежести.
По умолчанию `inactive` равен 10 минутам. |
#### NOTE
В Angie PRO можно задавать несколько директив proxy_cache_path с одним и
тем же значением `keys_zone`. Размер зоны разделяемой памяти можно
указывать только в первой из них. Выбор между директивами будет
производиться на основе параметра `path` соответствующей директивы
[proxy_cache](#proxy-cache).
Специальный процесс **менеджера кэша** следит за максимальным размером кэша, а также за минимальным объемом свободного места на файловой системе с кэшем, и удаляет наименее востребованные данные при превышении максимального размера кэша или недостаточном объеме свободного места. Удаление данных происходит итерациями.
| `max_size` | максимальное пороговое значение размера кэша |
|---------------------|---------------------------------------------------------------------------------------------------------|
| `min_free` | минимальное пороговое значение объема свободного места на файловой системе с кэшем |
| `manager_files` | максимальное количество удаляемых элементов кэша за одну итерацию
По умолчанию: `100`. |
| `manager_threshold` | ограничивает время работы одной итерации
По умолчанию: `200` миллисекунд. |
| `manager_sleep` | время, в течение которого выдерживается пауза между итерациями
По умолчанию: `50` миллисекунд. |
Через минуту после запуска Angie активируется специальный процесс **загрузчика кэша**.
Он сканирует файловую систему в поисках ранее закэшированных данных
и загружает эту информацию в область кэша.
Этот процесс выполняется итеративно;
каждая итерация обрабатывает ограниченное количество элементов, заданное параметром `loader_files`,
следит за тем, чтобы не превышать `loader_threshold`,
затем делает короткую паузу, заданную `loader_sleep`,
перед переходом к следующей партии.
Итерации продолжаются
до тех пор, пока загрузчик не обработает все существующие записи кэша на диске:
| `loader_files` | максимальное количество элементов кэша к загрузке в одну итерацию
По умолчанию: `100` |
|--------------------|--------------------------------------------------------------------------------------------------------|
| `loader_threshold` | ограничивает время работы одной итерации
По умолчанию: `200` миллисекунд |
| `loader_sleep` | время, в течение которого выдерживается пауза между итерациями
По умолчанию: `50` миллисекунд |
#### NOTE
Указание файла для параметра `keys_zone`
не влияет на работу загрузчика кэша.
### proxy_cache_revalidate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_revalidate` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `proxy_cache_revalidate off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает ревалидацию просроченных элементов кэша при помощи условных запросов с полями заголовка `If-Modified-Since` и `If-None-Match` .
### proxy_cache_use_stale
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_use_stale` `error` | `timeout` | `invalid_header` | `updating` | `http_500` | `http_502` | `http_503` | `http_504` | `http_403` | `http_404` | `http_429` | `off` ...; |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `proxy_cache_use_stale off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, в каких случаях можно использовать устаревший кэшированный ответ. Параметры директивы совпадают с параметрами директивы [proxy_next_upstream](#proxy-next-upstream).
| `error` | Позволяет использовать устаревший кэшированный ответ при невозможности выбора проксированного сервера для обработки запроса. |
|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `updating` | Дополнительный параметр, разрешает использовать устаревший кэшированный ответ, если на данный момент он уже обновляется. Это позволяет минимизировать число обращений к проксированным серверам при обновлении кэшированных данных. |
Использование устаревшего кэшированного ответа может также быть разрешено непосредственно в заголовке ответа на определенное количество секунд после того, как ответ устарел:
* Расширение [stale-while-revalidate](https://datatracker.ietf.org/doc/html/rfc5861#section-3) поля заголовка `Cache-Control` разрешает использовать устаревший кэшированный ответ, если на данный момент он уже обновляется.
* Расширение [stale-if-error](https://datatracker.ietf.org/doc/html/rfc5861#section-4) поля заголовка `Cache-Control` разрешает использовать устаревший кэшированный ответ в случае ошибки.
#### NOTE
Такой способ менее приоритетен, чем задание параметров директивы.
Чтобы минимизировать число обращений к проксированным серверам при заполнении нового элемента кэша, можно воспользоваться директивой [proxy_cache_lock](#proxy-cache-lock).
### proxy_cache_valid
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_valid` [код ...] время; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает время кэширования для разных кодов ответа. Например, директивы
```nginx
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
```
задают время кэширования 10 минут для ответов с кодами 200 и 302 и 1 минуту для ответов с кодом 404.
Если указано только время кэширования,
```nginx
proxy_cache_valid 5m;
```
то кэшируются только ответы 200, 301 и 302.
Кроме того, можно кэшировать любые ответы с помощью параметра `any`:
```nginx
proxy_cache_valid 200 302 10m;
proxy_cache_valid 301 1h;
proxy_cache_valid any 1m;
```
#### NOTE
Параметры кэширования могут также быть заданы непосредственно в заголовке ответа. Такой способ приоритетнее, чем задание времени кэширования с помощью директивы.
* Поле заголовка `X-Accel-Expires` задает время кэширования ответа в секундах. Значение 0 запрещает кэшировать ответ. Если значение начинается с префикса @, оно задает абсолютное время в секундах с начала эпохи, до которого ответ может быть кэширован.
* Если в заголовке нет поля `X-Accel-Expires`, параметры кэширования определяются по полям заголовка `Expires` или `Cache-Control`.
* Ответ, в заголовке которого есть поле `Set-Cookie`, не будет кэшироваться.
* Ответ, в заголовке которого есть поле `Vary` со специальным значением "\*", не будет кэшироваться. Ответ, в заголовке которого есть поле `Vary` с другим значением, будет кэширован с учетом соответствующих полей заголовка запроса.
Обработка одного или более из этих полей заголовка может быть отключена при помощи директивы [proxy_ignore_headers](#proxy-ignore-headers).
### proxy_connect_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_connect_timeout` время; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `proxy_connect_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут для установления соединения с проксированным сервером. Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.
### proxy_connection_drop
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_connection_drop` время | `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| По умолчанию | `proxy_connection_drop off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Настраивает завершение всех соединений с проксируемым сервером,
если он был удален из группы или помечен как постоянно недоступный
в результате процесса [reresolve](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve)
или [команды API](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods) `DELETE`.
Соединение завершается, когда обрабатывается следующее событие чтения или записи
для клиента или проксируемого сервера.
Установка времени включает [таймаут](https://angie.software//angie/docs/configuration/configfile.md#syntax) до завершения соединения;
при выборе значения `on` соединения завершаются немедленно.
### proxy_cookie_domain
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cookie_domain` `off`;
`proxy_cookie_domain` домен замена; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| По умолчанию | `proxy_cookie_domain off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает текст, который нужно изменить в атрибуте domain полей `Set-Cookie` заголовка ответа проксируемого сервера. Предположим, проксируемый сервер вернул поле заголовка `Set-Cookie` с атрибутом "domain=localhost". Директива
```nginx
proxy_cookie_domain localhost example.org;
```
перепишет данный атрибут в виде "domain=example.org".
Точка в начале строк домен и замена, а равно как и в атрибуте domain игнорируется. Регистр значения не имеет.
В строках домен и замена можно использовать переменные:
```nginx
proxy_cookie_domain www.$host $host;
```
Директиву также можно задать при помощи регулярных выражений. При этом домен должен начинаться с символа "~". Регулярное выражение может содержать именованные и позиционные группы захвата, а замена ссылаться на них:
```nginx
proxy_cookie_domain ~\.(?P[-0-9a-z]+\.[a-z]+)$ $sl_domain;
```
На одном уровне может быть указано несколько директив proxy_cookie_domain:
```nginx
proxy_cookie_domain localhost example.org;
proxy_cookie_domain ~\.([a-z]+\.[a-z]+)$ $1;
```
Если к cookie могут быть применены несколько директив, будет выбрана первая из них.
Параметр `off` отменяет действие унаследованных с предыдущего уровня конфигурации директив proxy_cookie_domain.
### proxy_cookie_flags
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cookie_flags` `off` | cookie [флаг ...]; |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| По умолчанию | `proxy_cookie_flags off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает один или несколько флагов для cookie. В качестве cookie можно использовать текст, переменные и их комбинации. В качестве флага можно использовать текст, переменные и их комбинации.
Параметры secure, httponly, samesite=strict, samesite=lax, samesite=none добавляют соответствующие флаги.
Параметры nosecure, nohttponly, nosamesite удаляют соответствующие флаги.
Cookie также можно задать при помощи регулярных выражений. При этом cookie должен начинаться с символа "~".
На одном уровне конфигурации может быть указано несколько директив proxy_cookie_flags:
```nginx
proxy_cookie_flags one httponly;
proxy_cookie_flags ~ nosecure samesite=strict;
```
Если к cookie могут быть применены несколько директив, будет выбрана первая из них. В данном примере флаг httponly добавляется к cookie one, для остальных cookie добавляется флаг samesite=strict и удаляется флаг secure.
Параметр `off` отменяет действие всех директив proxy_cookie_flags на данном уровне.
### proxy_cookie_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cookie_path` `off`;
`proxy_cookie_path` путь замена; |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| По умолчанию | `proxy_cookie_path off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает текст, который нужно изменить в атрибуте path полей `Set-Cookie` заголовка ответа проксируемого сервера. Предположим, проксируемый сервер вернул поле заголовка `Set-Cookie` с атрибутом "path=/two/some/uri/". Директива
```nginx
proxy_cookie_path /two/ /;
```
перепишет данный атрибут в виде "path=/some/uri/".
В строках путь и замена можно использовать переменные:
```nginx
proxy_cookie_path $uri /some$uri;
```
Директиву также можно задать при помощи регулярных выражений. При этом путь должен начинаться либо с символа "~", если при сравнении следует учитывать регистр символов, либо с символов "~\*", если регистр символов учитывать не нужно. Регулярное выражение может содержать именованные и позиционные группы захвата, а замена ссылаться на них:
```nginx
proxy_cookie_path ~*^/user/([^/]+) /u/$1;
```
На одном уровне может быть указано несколько директив proxy_cookie_path:
```nginx
proxy_cookie_path /one/ /;
proxy_cookie_path / /two/;
```
Если к cookie могут быть применены несколько директив, будет выбрана первая из них.
Параметр `off` отменяет действие унаследованных с предыдущего уровня конфигурации директив proxy_cookie_path.
### proxy_force_ranges
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_force_ranges` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `proxy_force_ranges off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Включает поддержку диапазонов запрашиваемых байт (byte-range) для кэшированных и некэшированных ответов проксируемого сервера вне зависимости от наличия поля `Accept-Ranges` в заголовках этих ответов.
### proxy_headers_hash_bucket_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_headers_hash_bucket_size` размер; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `proxy_headers_hash_bucket_size 64;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает размер корзины для хэш-таблиц, используемых директивами [proxy_hide_header](#proxy-hide-header) и [proxy_set_header](#proxy-set-header). Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
### proxy_headers_hash_max_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_headers_hash_max_size` размер; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `proxy_headers_hash_max_size 512;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает максимальный размер хэш-таблиц, используемых директивами [proxy_hide_header](#proxy-hide-header) и [proxy_set_header](#proxy-set-header). Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
### proxy_hide_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_hide_header` поле; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
По умолчанию Angie не передает клиенту поля заголовка `Date`, `Server`, `X-Pad` и `X-Accel-...` из ответа проксированного сервера. Директива proxy_hide_header задает дополнительные поля, которые не будут передаваться. Если же передачу полей нужно разрешить, можно воспользоваться директивой [proxy_pass_header](#proxy-pass-header).
### proxy_http_version
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_http_version` `1.0` | `1.1` | `3`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------|
| По умолчанию | `proxy_http_version 1.0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location, limit_except |
Задает версию протокола HTTP для проксирования.
По умолчанию используется версия 1.0.
Для работы
[постоянных соединений](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive)
рекомендуется версия 1.1 или выше.
### proxy_http3_hq
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_http3_hq` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `proxy_http3_hq off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Отключает или включает особый режим cогласования `hq-interop`,
используемый в
[функциональных тестах](https://github.com/marten-seemann/quic-interop-runner)
[QUIC](#proxy-http-version),
на которые полагается Angie.
#### WARNING
Включайте этот режим только для запуска специализированных тестов,
которым в явной форме необходим данный режим.
### proxy_http3_max_concurrent_streams
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_http3_max_concurrent_streams` число; |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| По умолчанию | `proxy_http3_max_concurrent_streams 128;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Инициализирует настройки HTTP/3 и QUIC,
а также задает максимальное число параллельных HTTP/3-потоков в
[соединении](#proxy-http-version).
Требует включения [постоянных соединений](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive).
### proxy_http3_max_table_capacity
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_http3_max_table_capacity` число; |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| Значение по умолчанию | `proxy_http3_max_table_capacity 4096;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет емкость [динамической таблицы](https://www.ietf.org/archive/id/draft-ietf-quic-qpack-20.html#name-dynamic-table)
для прокси-соединений.
#### NOTE
Похожая директива [http3_max_table_capacity](https://angie.software//angie/docs/configuration/modules/http/http_v3.md#http3-max-table-capacity)
задает это значение для серверных соединений.
Чтобы избежать ошибок, использование динамической таблицы
отключается при включенном кэшировании в режиме проксирования.
### proxy_http3_stream_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_http3_stream_buffer_size` размер; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `proxy_http3_stream_buffer_size 64k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает [размер](https://angie.software//angie/docs/configuration/configfile.md#syntax) буфера, используемого для чтения и записи
[QUIC-потоков](#proxy-http-version).
### proxy_ignore_client_abort
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ignore_client_abort` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | `proxy_ignore_client_abort off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, закрывать ли соединение с проксируемым сервером в случае, если клиент закрыл соединение, не дождавшись ответа.
### proxy_ignore_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ignore_headers` поле ...; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Запрещает обработку некоторых полей заголовка из ответа проксированного сервера. В директиве можно указать поля `X-Accel-Redirect`, `X-Accel-Expires`, `X-Accel-Limit-Rate`, `X-Accel-Buffering`, `X-Accel-Charset`, `Expires`, `Cache-Control`, `Set-Cookie` и `Vary`.
Если не запрещено, обработка этих полей заголовка заключается в следующем:
* `X-Accel-Expires`, `Expires`, `Cache-Control`, `Set-Cookie` и `Vary` задают [параметры кэширования](#proxy-cache-valid) ответа;
* `X-Accel-Redirect` производит [внутреннее перенаправление](https://angie.software//angie/docs/configuration/modules/http/index.md#internal) на указанный URI;
* `X-Accel-Limit-Rate` задает [ограничение скорости](https://angie.software//angie/docs/configuration/modules/http/index.md#limit-rate) передачи ответа клиенту;
* `X-Accel-Buffering` включает или выключает [буферизацию](#proxy-buffering) ответа;
* `X-Accel-Charset` задает желаемую [кодировку](https://angie.software//angie/docs/configuration/modules/http/http_charset.md#id3) ответа.
### proxy_intercept_errors
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_intercept_errors` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `proxy_intercept_errors off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, передавать ли клиенту проксированные ответы с кодом больше либо равным 300, или же перехватывать их и перенаправлять на обработку Angie с помощью директивы [error_page](https://angie.software//angie/docs/configuration/modules/http/index.md#error-page).
### proxy_limit_rate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_limit_rate` скорость; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `proxy_limit_rate 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает скорость чтения ответа от проксируемого сервера.
Скорость задается в байтах в секунду; можно использовать переменные.
| `0` | отключает ограничение скорости |
|-------|----------------------------------|
#### NOTE
Ограничение устанавливается на запрос, поэтому, если Angie одновременно откроет два соединения к проксируемому серверу, суммарная скорость будет вдвое выше заданного ограничения. Ограничение работает только в случае, если включена [буферизация](#proxy-buffering) ответов проксируемого сервера.
### proxy_max_temp_file_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_max_temp_file_size` размер; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `proxy_max_temp_file_size 1024m;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если включена [буферизация](#proxy-buffering) ответов проксируемого сервера, и ответ не вмещается целиком в буферы, заданные директивами [proxy_buffer_size](#proxy-buffer-size) и [proxy_buffers](#proxy-buffers), часть ответа может быть записана во временный файл. Эта директива задает максимальный размер временного файла. Размер данных, сбрасываемых во временный файл за один раз, задается директивой [proxy_temp_file_write_size](#proxy-temp-file-write-size).
| `0` | отключает возможность буферизации ответов во временные файлы |
|-------|----------------------------------------------------------------|
#### NOTE
Данное ограничение не распространяется на ответы, которые будут [кэшированы](#proxy-cache) или сохранены [на диске](#proxy-store).
### proxy_method
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_method` метод; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает HTTP-метод, который будет использоваться в передаваемых на проксируемый сервер запросах вместо метода из клиентского запроса. В значении параметра допустимо использование переменных.
### proxy_next_upstream
#### Versionchanged
Изменено в версии 1.11.0: Если все серверы в upstream-группе недоступны или возвращают ответ со
статусом, который считается ошибочным согласно этой директиве (и ей
подобным для других протоколов), Angie теперь всегда возвращает
собственную страницу ошибки вместо ответа последнего сервера.
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_next_upstream` `error` | `timeout` | `invalid_header` | `http_500` | `http_502` | `http_503` | `http_504` | `http_403` | `http_404` | `http_429` | `non_idempotent` | `off` ...; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `proxy_next_upstream error timeout;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, в каких случаях запрос будет передан следующему в группе [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) серверу:
| `error` | произошла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `timeout` | произошел таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
| `invalid_header` | сервер вернул пустой или неверный ответ; |
| `http_500` | сервер вернул ответ с кодом 500; |
| `http_502` | сервер вернул ответ с кодом 502; |
| `http_503` | сервер вернул ответ с кодом 503; |
| `http_504` | сервер вернул ответ с кодом 504; |
| `http_403` | сервер вернул ответ с кодом 403; |
| `http_404` | сервер вернул ответ с кодом 404; |
| `http_429` | сервер вернул ответ с кодом 429; |
| `non_idempotent` | обычно запросы с [неидемпотентным](https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2) методом (POST, LOCK, PATCH) не передаются на другой сервер, если запрос серверу группы уже был отправлен; включение параметра явно разрешает повторять подобные запросы; |
| `off` | запрещает передачу запроса следующему серверу. |
Если все upstream‑серверы недоступны или возвращают ответ со статусом,
считающимся ошибкой для `proxy_next_upstream`, Angie возвращает
собственную стандартную страницу ошибки вместо тела ответа от последнего
upstream‑сервера.
#### NOTE
Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту еще ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа клиенту, то действие директивы на такой запрос не распространяется.
Директива также определяет, что считается [неудачной попыткой](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) работы с сервером.
| `error`
`timeout`
`invalid_header` | всегда считаются неудачными попытками, даже если они не указаны в директиве |
|--------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
| `http_500`
`http_502`
`http_503`
`http_504`
`http_429` | считаются неудачными попытками, только если они указаны в директиве |
| `http_403`
`http_404` | никогда не считаются неудачными попытками |
Передача запроса следующему серверу может быть ограничена по [количеству попыток](#proxy-next-upstream-tries) и по [времени](#proxy-next-upstream-timeout).
### proxy_next_upstream_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_next_upstream_timeout` время; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `proxy_next_upstream_timeout 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает время, в течение которого возможна передача запроса [следующему](#proxy-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### proxy_next_upstream_tries
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_next_upstream_tries` число; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `proxy_next_upstream_tries 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает число допустимых попыток для передачи запроса [следующему](#proxy-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### proxy_no_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_no_cache` строка ...; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает условия, при которых ответ не будет сохраняться в кэш. Если значение хотя бы одного из строковых параметров непустое и не равно "0", то ответ не будет сохранен:
```nginx
proxy_no_cache $cookie_nocache $arg_nocache$arg_comment;
proxy_no_cache $http_pragma $http_authorization;
```
Можно использовать совместно с директивой [proxy_cache_bypass](#proxy-cache-bypass).
### proxy_pass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_pass` uri; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location, if в location, limit_except |
Задает протокол и адрес проксируемого сервера, а также необязательный URI, на который должен отображаться location. В качестве протокола можно указать `http` или `https`. Адрес может быть указан в виде доменного имени или IP-адреса, и необязательного порта:
```nginx
proxy_pass http://localhost:8000/uri/;
```
или в виде пути UNIX-сокета, который указывается после слова `unix` и заключается в двоеточия:
```nginx
proxy_pass http://unix:/tmp/backend.socket:/uri/;
```
Если доменному имени соответствует несколько адресов, то все они будут использоваться по очереди (round-robin). Кроме того, в качестве адреса можно указать [группу серверов](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).
В значении параметра можно использовать переменные. В этом случае, если адрес указан в виде доменного имени, имя ищется среди описанных групп серверов и если не найдено, то определяется с помощью [resolver](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver)'а.
URI запроса передается на сервер так:
* Если директива `proxy_pass` указана **с URI**, то при передаче запроса серверу часть [нормализованного](https://angie.software//angie/docs/configuration/modules/http/index.md#location) URI запроса, соответствующая location, заменяется на URI, указанный в директиве:
```nginx
location /name/ {
proxy_pass http://127.0.0.1/remote/;
}
```
* Если директива `proxy_pass` указана **без URI**, то при обработке первоначального запроса на сервер передается URI запроса в том же виде, в каком его прислал клиент, а при обработке измененного URI - нормализованный URI запроса целиком:
```nginx
location /some/path/ {
proxy_pass http://127.0.0.1;
}
```
В ряде случаев часть URI запроса, подлежащую замене, выделить невозможно:
* Если `location` задан регулярным выражением, а также в именованных `location`.
В этих случаях `proxy_pass` следует указывать без URI.
* Если внутри проксируемого `location` с помощью директивы [rewrite](https://angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) изменяется URI, и именно с этой конфигурацией будет обрабатываться запрос (break):
```nginx
location /name/ {
rewrite /name/([^/]+) /users?name=$1 break;
proxy_pass http://127.0.0.1;
}
```
В этом случае URI, указанный в директиве, игнорируется, и на сервер передается измененный URI запроса целиком.
* При использовании переменных в proxy_pass:
```nginx
location /name/ {
proxy_pass http://127.0.0.1$request_uri;
}
```
В этом случае если в директиве указан URI, он передается на сервер как есть, заменяя URI первоначального запроса.
Проксирование WebSocket требует особой [настройки](https://angie.software//angie/docs/configuration/processing.md#websocket-proxy).
#### NOTE
Если `proxy_pass` стоит в `location` с косой чертой в конце префикса
(например, `location /name/`),
и при этом в директиве [auto_redirect](https://angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) указано `default`,
запросы без косой черты в конце будут перенаправляться (`/name -> /name/`).
### proxy_pass_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_pass_header` поле ...; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает передавать от проксируемого сервера клиенту [запрещенные для передачи](#proxy-hide-header) поля заголовка.
### proxy_pass_request_body
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_pass_request_body` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| По умолчанию | `proxy_pass_request_body on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запретить передачу исходного тела запроса на проксируемый сервер.
```nginx
location /x-accel-redirect-here/ {
proxy_method GET;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_pass ...;
}
```
См. также директивы [proxy_set_header](#proxy-set-header) и [proxy_pass_request_headers](#proxy-pass-request-headers).
### proxy_pass_request_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_pass_request_headers` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | `proxy_pass_request_headers on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запретить передачу полей заголовка исходного запроса на проксируемый сервер.
```nginx
location /x-accel-redirect-here/ {
proxy_method GET;
proxy_pass_request_headers off;
proxy_pass_request_body off;
proxy_pass ...;
}
```
См. также директивы [proxy_set_header](#proxy-set-header) и [proxy_pass_request_body](#proxy-pass-request-body).
### proxy_pass_trailers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_pass_trailers` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `proxy_pass_trailers off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает передачу полей трейлеров от проксируемого сервера клиенту.
Секция трейлеров в HTTP/1.1 [включается явно](https://datatracker.ietf.org/doc/html/rfc9110#section-6.5.1).
```nginx
location / {
proxy_http_version 1.1;
proxy_set_header Connection "te";
proxy_set_header TE "trailers";
proxy_pass_trailers on;
proxy_pass ...;
}
```
### proxy_quic_active_connection_id_limit
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_quic_active_connection_id_limit` число; |
|------------------------------------------------------------------------------------------|--------------------------------------------------|
| По умолчанию | `proxy_quic_active_connection_id_limit 2;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает значение транспортного параметра [QUIC](#proxy-http-version)
`active_connection_id_limit`.
Это максимальное число активных
[идентификаторов соединений](https://www.rfc-editor.org/rfc/rfc9000.html#name-connection-id),
поддерживаемых для одного сервера.
### proxy_quic_gso
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_quic_gso` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `proxy_quic_gso off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Отключает или включает отправку данных в оптимизированном пакетном режиме
[QUIC](#proxy-http-version),
использующем программное снижение нагрузки путем сегментации
([generic segmentation offload](https://docs.kernel.org/networking/segmentation-offloads.html#generic-segmentation-offload)).
### proxy_quic_host_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_quic_host_key` файл; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает файл с секретным ключом,
применяемым в
[QUIC](#proxy-http-version)
при шифровании токенов
[Stateless Reset](https://www.rfc-editor.org/rfc/rfc9000.html#name-stateless-reset)
и
[Address Validation](https://www.rfc-editor.org/rfc/rfc9000.html#address-validation).
По умолчанию случайный ключ создается при каждом перезапуске.
Токены, созданные при помощи старых ключей, не принимаются.
### proxy_read_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_read_timeout` время; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `proxy_read_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при чтении ответа проксированного сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени проксируемый сервер ничего не передаст, соединение закрывается.
### proxy_redirect
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_redirect` `default`;
`proxy_redirect` `off`;
`proxy_redirect` перенаправление замена; |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `proxy_redirect default;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает текст, который нужно изменить в полях заголовка "Location" и "Refresh" в ответе проксируемого сервера.
Предположим, проксируемый сервер вернул поле заголовка:
```console
Location: http://localhost:8000/two/some/uri/
```
Директива
```nginx
proxy_redirect http://localhost:8000/two/ http://frontend/one/;
```
перепишет эту строку в виде:
```console
Location: http://frontend/one/some/uri/
```
В заменяемой строке можно не указывать имя сервера:
```nginx
proxy_redirect http://localhost:8000/two/ /;
```
тогда будут подставлены основное имя сервера и порт, если он отличен от 80.
Стандартная замена, задаваемая параметром `default`, использует параметры директив [location](https://angie.software//angie/docs/configuration/modules/http/index.md#location) и [proxy_pass](#proxy-pass). Поэтому две нижеприведенные конфигурации одинаковы:
```nginx
location /one/ {
proxy_pass http://upstream:port/two/;
proxy_redirect default;
```
```nginx
location /one/ {
proxy_pass http://upstream:port/two/;
proxy_redirect http://upstream:port/two/ /one/;
```
#### WARNING
Параметр `default` недопустим, если в [proxy_pass](#proxy-pass) используются переменные.
В строке замена можно использовать переменные:
```nginx
proxy_redirect http://localhost:8000/ http://$host:$server_port/;
```
В строке перенаправление тоже можно использовать переменные:
```nginx
proxy_redirect http://$proxy_host:8000/ /;
```
Директиву также можно задать при помощи регулярных выражений. При этом перенаправление должно начинаться либо с символа "~", если при сравнении следует учитывать регистр символов, либо с символов "~\*", если регистр символов учитывать не нужно. Регулярное выражение может содержать именованные и позиционные группы захвата, а замена ссылаться на них:
```nginx
proxy_redirect ~^(http://[^:]+):\d+(/.+)$ $1$2;
proxy_redirect ~*/user/([^/]+)/(.+)$ http://$1.example.com/$2;
```
На одном уровне может быть указано несколько директив proxy_redirect:
```nginx
proxy_redirect default;
proxy_redirect http://localhost:8000/ /;
proxy_redirect http://www.example.com/ /;
```
Если к полям заголовка в ответе проксируемого сервера могут быть применены несколько директив, будет выбрана первая из них.
Параметр `off` отменяет действие унаследованных с предыдущего уровня конфигурации директив proxy_redirect.
С помощью этой директивы можно также добавлять имя хоста к относительным перенаправлениям, выдаваемым проксируемым сервером:
```nginx
proxy_redirect / /;
```
### proxy_request_buffering
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_request_buffering` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| По умолчанию | `proxy_request_buffering on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает использовать буферизацию тела запроса клиента.
| `on` | тело запроса полностью [читается](https://angie.software//angie/docs/configuration/modules/http/index.md#client-body-buffer-size) от клиента перед отправкой запроса на проксируемый сервер. |
|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | тело запроса отправляется на проксируемый сервер сразу же по мере его поступления. В этом случае запрос не может быть передан [следующему серверу](#proxy-next-upstream), если Angie уже начал отправку тела запроса. |
Если для отправки тела исходного запроса используется HTTP/1.1 и передача данных частями (chunked transfer encoding), то тело запроса буферизуется независимо от значения директивы, если для проксирования также не [включен](#proxy-http-version) HTTP/1.1.
### proxy_send_lowat
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_send_lowat` размер; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `proxy_send_lowat 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
При установке директивы в ненулевое значение Angie будет пытаться
минимизировать число операций отправки на исходящих соединениях с проксируемым
сервером либо при помощи флага `NOTE_LOWAT` метода [kqueue](https://angie.software//angie/docs/configuration/processing.md#kqueue), либо при
помощи параметра сокета `SO_SNDLOWAT`, с указанным размером.
#### NOTE
Эта директива игнорируется на Linux, Solaris и Windows.
### proxy_send_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_send_timeout` время; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `proxy_send_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при передаче запроса проксируемому серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени проксируемый сервер не примет новых данных, соединение закрывается.
### proxy_set_body
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_set_body` значение; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет переопределить тело запроса, передаваемое на проксируемый сервер. В качестве значения можно использовать текст, переменные и их комбинации.
### proxy_set_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_set_header` поле значение; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `proxy_set_header Host $proxy_host;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет переопределять или добавлять поля заголовка запроса, [передаваемые](#proxy-pass-request-headers) проксируемому серверу. В качестве значения можно использовать текст, переменные и их комбинации. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы proxy_set_header. По умолчанию переопределяются только два поля:
```nginx
proxy_set_header Host $proxy_host;
proxy_set_header Connection close;
```
Если включено кэширование, поля заголовка `If-Modified-Since` , `If-Unmodified-Since` , `If-None-Match` , `If-Match` , `Range` и `If-Range` исходного запроса не передаются на проксируемый сервер.
Неизмененное поле заголовка запроса "Host" можно передать так:
```nginx
proxy_set_header Host $http_host;
```
Однако, если это поле отсутствует в заголовке запроса клиента, то ничего передаваться не будет. В этом случае лучше воспользоваться переменной [$host](https://angie.software//angie/docs/configuration/modules/http/index.md#v-host) - ее значение равно имени сервера в поле "Host" заголовка запроса, или же основному имени сервера, если поля нет:
```nginx
proxy_set_header Host $host;
```
Кроме того, можно передать имя сервера вместе с портом проксируемого сервера:
```nginx
proxy_set_header Host $host:$proxy_port;
```
Если значение поля заголовка — пустая строка, то поле вообще не будет передаваться проксируемому серверу:
```nginx
proxy_set_header Accept-Encoding "";
```
### proxy_socket_keepalive
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_socket_keepalive` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `proxy_socket_keepalive off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Конфигурирует поведение "TCP keepalive" для исходящих соединений к проксируемому серверу.
| `""` | По умолчанию для сокета действуют настройки операционной системы. |
|--------|---------------------------------------------------------------------|
| `on` | для сокета включается параметр SO_KEEPALIVE |
### proxy_ssl_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_certificate` файл [файл]; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с сертификатом в формате PEM для аутентификации на проксируемом HTTPS-сервере. В имени файла можно использовать переменные.
При включенном [proxy_ssl_ntls](#proxy-ssl-ntls) директива принимает два аргумента вместо одного:
```nginx
location /proxy {
proxy_ssl_ntls on;
proxy_ssl_certificate sign.crt enc.crt;
proxy_ssl_certificate_key sign.key enc.key;
proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";
proxy_pass https://backend:443;
}
```
### proxy_ssl_certificate_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_certificate_cache` `off`;
`proxy_ssl_certificate_cache` `max=`N [`inactive=`time] [`valid=`time]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| Значение по умолчанию | `proxy_ssl_certificate_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет кэш для хранения [SSL-сертификатов](#proxy-ssl-certificate) и [секретных ключей](#proxy-ssl-certificate-key), заданных через переменные.
Директива поддерживает следующие параметры:
- `max` — устанавливает максимальное количество элементов в кэше. При переполнении кэша
удаляются наименее недавно использованные (LRU) элементы.
- `inactive` — определяет время, после которого элемент будет удален, если
к нему не было обращений. Значение по умолчанию — 10 секунд.
- `valid` — определяет время, в течение которого элемент кэша считается
действительным и может использоваться повторно. Значение по умолчанию — 60 секунд. По истечении этого времени
сертификаты перезагружаются или проходят повторную проверку.
- `off` — отключает кэш.
Пример:
```nginx
proxy_ssl_certificate $proxy_ssl_server_name.crt;
proxy_ssl_certificate_key $proxy_ssl_server_name.key;
proxy_ssl_certificate_cache max=1000 inactive=20s valid=1m;
```
### proxy_ssl_certificate_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_certificate_key` файл [файл]; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с секретным ключом в формате PEM для аутентификации на проксируемом HTTPS-сервере.
Вместо файла можно указать значение `engine:`name`:id`, которое загружает ключ с указанным id из OpenSSL engine с заданным именем.
Вместо файла можно указать значение `store:scheme:id`, которое используется для загрузки ключа с указанным id и URI-схемой scheme, зарегистрированной в OpenSSL provider, например [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).
В имени файла можно использовать переменные.
При включенном [proxy_ssl_ntls](#proxy-ssl-ntls) директива принимает два аргумента вместо одного:
```nginx
location /proxy {
proxy_ssl_ntls on;
proxy_ssl_certificate sign.crt enc.crt;
proxy_ssl_certificate_key sign.key enc.key;
proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";
proxy_pass https://backend:443;
}
```
### proxy_ssl_ciphers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_ciphers` шифры; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `proxy_ssl_ciphers DEFAULT;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Описывает разрешенные шифры для запросов к проксируемому HTTPS-серверу. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL.
Список шифров зависит от установленной версии OpenSSL.
Полный список можно посмотреть с помощью команды `openssl ciphers`.
#### WARNING
Директива `proxy_ssl_ciphers` *не* настраивает шифры для TLS 1.3 при
использовании OpenSSL. Для настройки шифров TLS 1.3 в OpenSSL используйте
директиву [proxy_ssl_conf_command](#proxy-ssl-conf-command), добавленную для расширенной
конфигурации SSL.
- В LibreSSL шифры TLS 1.3 *можно* настраивать с помощью
`proxy_ssl_ciphers`.
- В BoringSSL шифры TLS 1.3 настроить невозможно.
### proxy_ssl_conf_command
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_conf_command` имя значение; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает произвольные конфигурационные [команды](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) OpenSSL при установлении соединения с проксируемым HTTPS-сервером.
#### NOTE
Директива поддерживается при использовании OpenSSL 1.0.2 и выше.
Чтобы настроить шифры TLS 1.3 в OpenSSL, используйте команду `ciphersuites`.
На одном уровне может быть указано несколько директив proxy_ssl_conf_command. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы proxy_ssl_conf_command.
#### WARNING
Следует учитывать, что изменение настроек OpenSSL напрямую может привести к неожиданному поведению.
### proxy_ssl_crl
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_crl` файл; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Указывает файл с отозванными сертификатами (CRL) в формате PEM, используемыми при [проверке](#proxy-ssl-verify) сертификата проксируемого HTTPS-сервера.
### proxy_ssl_name
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_name` имя; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `proxy_ssl_name $proxy_host;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет переопределить имя сервера, используемое при [проверке](#proxy-ssl-verify) сертификата проксируемого HTTPS-сервера, а также для [передачи его через SNI](#proxy-ssl-server-name) при установлении соединения с проксируемым HTTPS-сервером.
По умолчанию используется имя хоста из URL'а, заданного директивой [proxy_pass](#proxy-pass).
### proxy_ssl_ntls
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_ntls` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `proxy_ssl_ntls off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Включает клиентскую поддержку NTLS при использовании TLS библиотеки [TongSuo](https://github.com/Tongsuo-Project/Tongsuo).
```nginx
location /proxy {
proxy_ssl_ntls on;
proxy_ssl_certificate sign.crt enc.crt;
proxy_ssl_certificate_key sign.key enc.key;
proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";
proxy_pass https://backend:443;
}
```
#### NOTE
Angie необходимо собрать с использованием параметра конфигурации `--with-ntls`, с соответствующей SSL библиотекой с поддержкой NTLS
```default
./configure --with-openssl=../Tongsuo-8.3.0 \
--with-openssl-opt=enable-ntls \
--with-ntls
```
### proxy_ssl_password_file
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_password_file` файл; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с паролями от [секретных ключей](#proxy-ssl-certificate-key), где каждый пароль указан на отдельной строке. Пароли применяются по очереди в момент загрузки ключа.
### proxy_ssl_protocols
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`]; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| По умолчанию | `proxy_ssl_protocols TLSv1.2 TLSv1.3;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает указанные протоколы для запросов к проксируемому HTTPS-серверу.
### proxy_ssl_server_name
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_server_name` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `proxy_ssl_server_name off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает передачу имени сервера,
заданного директивой [proxy_ssl_name](#proxy-ssl-name),
через расширение
[Server Name Indication](http://en.wikipedia.org/wiki/Server_Name_Indication)
протокола TLS
(SNI,
[RFC 6066](https://datatracker.ietf.org/doc/html/rfc6066.html))
при установлении соединения с проксируемым HTTPS-сервером.
### proxy_ssl_session_reuse
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_session_reuse` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| По умолчанию | `proxy_ssl_session_reuse on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, использовать ли повторно SSL-сессии при работе с проксируемым сервером. Если в логах появляются ошибки "SSL3_GET_FINISHED:digest check failed", то можно попробовать выключить повторное использование сессий.
### proxy_ssl_trusted_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_trusted_certificate` файл; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с доверенными сертификатами CA в формате PEM, используемыми при [проверке](#proxy-ssl-verify) сертификата проксируемого HTTPS-сервера.
### proxy_ssl_verify
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_verify` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `proxy_ssl_verify off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает проверку сертификата проксируемого HTTPS-сервера.
### proxy_ssl_verify_depth
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_verify_depth` число; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `proxy_ssl_verify_depth 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Устанавливает глубину проверки в цепочке сертификатов проксируемого HTTPS-сервера.
### proxy_store
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_store` `on` | `off` | строка; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `proxy_store off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает сохранение на диск файлов.
| `on` | сохраняет файлы в соответствии с путями, указанными в директивах [alias](https://angie.software//angie/docs/configuration/modules/http/index.md#alias) или [root](https://angie.software//angie/docs/configuration/modules/http/index.md#root) |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | запрещает сохранение файлов |
Имя файла можно задать явно с помощью `строки` с переменными:
```nginx
proxy_store /data/www$original_uri;
```
Время изменения файлов выставляется согласно полученному полю `Last-Modified` в заголовке ответа. Ответ сначала записывается во временный файл, а потом этот файл переименовывается. Временный файл и постоянное место хранения ответа могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешевой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой системе, что и каталог с временными файлами, задаваемый директивой [proxy_temp_path](#proxy-temp-path) для данного location.
Директиву можно использовать для создания локальных копий статических неизменяемых файлов, например, так:
```nginx
location /images/ {
root /data/www;
error_page 404 = /fetch$uri;
}
location /fetch/ {
internal;
proxy_pass http://backend/;
proxy_store on;
proxy_store_access user:rw group:rw all:r;
proxy_temp_path /data/temp;
alias /data/www/;
}
```
или так:
```nginx
location /images/ {
root /data/www;
error_page 404 = @fetch;
}
location @fetch {
internal;
proxy_pass http://backend;
proxy_store on;
proxy_store_access user:rw group:rw all:r;
proxy_temp_path /data/temp;
root /data/www;
}
```
### proxy_store_access
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_store_access` пользователи:права ...; |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| По умолчанию | `proxy_store_access user:rw;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает права доступа для создаваемых файлов и каталогов, например,
```nginx
proxy_store_access user:rw group:rw all:r;
```
Если заданы какие-либо права для group или all, то права для user указывать необязательно:
```nginx
proxy_store_access group:rw all:r;
```
### proxy_temp_file_write_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_temp_file_write_size` размер; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `proxy_temp_file_write_size 8k|16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает размер данных, сбрасываемых во временный файл за один раз, при включенной буферизации ответов проксируемого сервера во временные файлы. По умолчанию размер ограничен двумя буферами, заданными директивами [proxy_buffer_size](#proxy-buffer-size) и [proxy_buffers](#proxy-buffers). Максимальный размер временного файла задается директивой [proxy_max_temp_file_size](#proxy-max-temp-file-size).
### proxy_temp_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_temp_path` путь [уровень1 [уровень2 [уровень3]]]\`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `proxy_temp_path proxy_temp;`
(путь зависит от [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-proxy-temp-path`) |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает имя каталога для хранения временных файлов с данными, полученными от проксируемых серверов. В каталоге может использоваться иерархия подкаталогов до трех уровней. Например, при такой конфигурации
```nginx
proxy_temp_path /spool/angie/proxy_temp 1 2;
```
временный файл будет следующего вида:
```nginx
/spool/angie/proxy_temp/7/45/00000123457
```
См. также параметр use_temp_path директивы [proxy_cache_path](#proxy-cache-path).
## Встроенные переменные
В модуле http_proxy есть встроенные переменные, которые можно использовать для формирования заголовков с помощью директивы [proxy_set_header](#proxy-set-header):
### `$proxy_host`
имя и порт проксируемого сервера, как указано в директиве [proxy_pass](#proxy-pass);
### `$proxy_port`
порт проксируемого сервера, как указано в директиве [proxy_pass](#proxy-pass), или стандартный порт протокола;
### `$proxy_add_x_forwarded_for`
поле заголовка запроса клиента `X-Forwarded-For` и добавленная к нему через запятую переменная [$remote_addr](https://angie.software//angie/docs/configuration/modules/http/index.md#v-remote-addr). Если же поля `X-Forwarded-For` в заголовке запроса клиента нет, то переменная [$proxy_add_x_forwarded_for](#v-proxy-add-x-forwarded-for) равна переменной [$remote_addr](https://angie.software//angie/docs/configuration/modules/http/index.md#v-remote-addr).
# https://angie.software/angie/docs/configuration/modules/http/http_random_index.md
# Random Index
Обслуживает запросы, оканчивающиеся косой чертой (`/`), и выдает случайный файл в качестве индексного файла каталога. Модуль выполняется до модуля `http_index`.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_random_index_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
## Пример конфигурации
```nginx
location / {
random_index on;
}
```
## Директивы
### random_index
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `random_index` `on` | `off`.; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `random_index off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Разрешает или запрещает в содержащем эту директиву `location` обработку этим модулем.
# https://angie.software/angie/docs/configuration/modules/http/http_realip.md
# RealIP
Позволяет менять адрес и необязательный порт клиента на переданные в указанном поле заголовка.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_realip_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
## Пример конфигурации
```nginx
set_real_ip_from 192.168.1.0/24;
set_real_ip_from 192.168.2.1;
set_real_ip_from 2001:0db8::/32;
real_ip_header X-Forwarded-For;
real_ip_recursive on;
```
## Директивы
### set_real_ip_from
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `set_real_ip_from` адрес | CIDR | `unix`:; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает доверенные адреса, которые передают верный адрес для замены. Если указано специальное значение `unix:`, доверенными будут считаться все UNIX-сокеты. Доверенные адреса могут быть также заданы при помощи имени хоста.
### real_ip_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `real_ip_header` поле | `X-Real-IP` | `X-Forwarded-For` | `proxy_protocol`; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
| По умолчанию | `real_ip_header X-Real-IP;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает поле заголовка запроса, значение которого будет использоваться для замены адреса клиента.
Значение поля заголовка запроса, содержащее необязательный порт, также используется для замены порта клиента. Адрес и порт должны быть указаны согласно [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986).
Параметр `proxy_protocol` меняет адрес клиента на указанный в заголовке PROXY-протокола. Протокол PROXY должен быть предварительно включен при помощи установки параметра proxy_protocol в директиве [listen](https://angie.software//angie/docs/configuration/modules/http/index.md#listen).
### real_ip_recursive
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `real_ip_recursive` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `real_ip_recursive off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
При выключенном рекурсивном поиске исходный адрес клиента, совпадающий с одним из доверенных адресов, заменяется на последний адрес, переданный в поле заголовка запроса, заданного директивой [real_ip_header](#real-ip-header). При включенном рекурсивном поиске исходный адрес клиента, совпадающий с одним из доверенных адресов, заменяется на последний не доверенный адрес, переданный в заданном поле заголовка запроса.
## Встроенные переменные
### `$realip_remote_addr`
хранит исходный адрес клиента
### `$realip_remote_port`
хранит исходный порт клиента
# https://angie.software/angie/docs/configuration/modules/http/http_referer.md
# Referer
Позволяет блокировать доступ к сайту для запросов с неверными значениями поля `Referer` в заголовке. Следует иметь в виду, что подделать запрос с нужным значением поля `Referer` не составляет большого труда, поэтому цель использования данного модуля заключается не в стопроцентном блокировании подобных запросов, а в блокировании массового потока запросов, сделанных обычными браузерами. Нужно также учитывать, что обычные браузеры могут не передавать поле `Referer` даже для верных запросов.
## Пример конфигурации
```nginx
valid_referers none blocked server_names
*.example.com example.* www.example.org/galleries/
~\.google\.;
if ($invalid_referer) {
return 403;
}
```
## Директивы
### referer_hash_bucket_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `referer_hash_bucket_size` размер; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `referer_hash_bucket_size 64;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location |
Задает размер корзины хэш-таблиц со значениями `Referer`. Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
### referer_hash_max_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `referer_hash_max_size` размер; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `referer_hash_max_size 2048;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location |
Задает максимальный размер хэш-таблиц со значениями `Referer`. Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
### valid_referers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `valid_referers` `none` | `blocked` | `server_names` | строка ...; |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location |
Задает значения поля `Referer` заголовка запроса, при которых встроенная переменная [$invalid_referer](#v-invalid-referer) будет иметь пустую строку в качестве значения. В противном случае значение переменной равно "1". Поиск совпадения производится без учета регистра символов.
Параметры могут быть следующие:
| `none` | поле `Referer` в заголовке запроса отсутствует; |
|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `blocked` | поле `Referer` в заголовке запроса присутствует, но его значение удалено межсетевым экраном (firewall) или прокси-сервером; к таким значениям относятся строки, не начинающиеся на "`http://`" или "`https://`"; |
| `server_names` | в поле `Referer` заголовка запроса указано одно из имен сервера; |
| `произвольная строка` | задает имя сервера и необязательное начало URI. В начале или конце имени сервера может быть "\*". При проверке порт сервера в поле `Referer` игнорируется; |
| `регулярное выражение` | в начале должен быть символ "~". Необходимо учитывать, что на совпадение с выражением будет проверяться текст, начинающийся после "`http://`" или "`https://`". |
Пример:
```nginx
valid_referers none blocked server_names
*.example.com example.* www.example.org/galleries/
~\.google\.;
```
## Встроенные переменные
### `$invalid_referer`
Пустая строка, если значение поля `Referer` заголовка запроса считается [правильным](#valid-referers), иначе "1".
# https://angie.software/angie/docs/configuration/modules/http/http_rewrite.md
# Rewrite
Позволяет изменять URI запроса с помощью регулярных выражений PCRE, делать перенаправления и выбирать конфигурацию по условию.
Директивы [break](#break), [if](#if), [return](#return), [rewrite](#id5) и [set](#set) обрабатываются в следующем порядке:
* последовательно выполняются директивы этого модуля, описанные на уровне `server`;
* в цикле:
> * ищется `location` по URI запроса;
> * последовательно выполняются директивы этого модуля, описанные в найденном `location`;
> * цикл повторяется, если URI запроса [изменялся](#id5), но [не более](https://angie.software//angie/docs/configuration/modules/http/index.md#internal) 10 раз.
## Директивы
### break
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `break`; |
|------------------------------------------------------------------------------------------|----------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location, if |
Завершает обработку текущего набора директив модуля `http_rewrite`.
Если директива указана внутри `location`, дальнейшая обработка запроса продолжается в этом `location`.
Пример:
```nginx
if ($slow) {
limit_rate 10k;
break;
}
```
### if
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `if` (условие) { ... } |
|------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location |
Проверяется указанное условие. Если оно истинно, то выполняются указанные в фигурных скобках директивы этого модуля и запросу назначается конфигурация, указанная внутри директивы `if`. Конфигурации внутри директив `if` наследуются с предыдущего уровня конфигурации.
#### WARNING
Хотя внутри блока `if` можно применять директивы других модулей,
делать это не рекомендуется,
так как это может привести к непредвиденному поведению.
В качестве условия могут быть заданы:
* имя переменной; ложными значениями переменной являются пустая строка или "0";
* сравнение переменной со строкой с помощью операторов "=" и "!=";
* соответствие переменной регулярному выражению с учетом регистра символов — "~" и без него — "~\*". В регулярных выражениях можно использовать группы захвата, которые затем доступны в виде переменных $1..$9. Также можно использовать отрицательные операторы "!~" и "!~\*". Если в регулярном выражении встречаются символы "}" или ";", то все выражение следует заключить в одинарные или двойные кавычки.
* проверка существования файла с помощью операторов "-f" и "!-f";
* проверка существования каталога с помощью операторов "-d" и "!-d";
* проверка существования файла, каталога или символической ссылки с помощью операторов "-e" и "!-e";
* проверка исполняемости файла с помощью операторов "-x" и "!-x".
Примеры:
```nginx
if ($http_user_agent ~ MSIE) {
rewrite ^(.*)$ /msie/$1 break;
}
if ($http_cookie ~* "id=([^;]+)(?:;|$)") {
set $id $1;
}
if ($request_method = POST) {
return 405;
}
if ($slow) {
limit_rate 10k;
}
if ($invalid_referer) {
return 403;
}
```
#### NOTE
Значение встроенной переменной [$invalid_referer](https://angie.software//angie/docs/configuration/modules/http/http_referer.md#v-invalid-referer) задается директивой [valid_referers](https://angie.software//angie/docs/configuration/modules/http/http_referer.md#valid-referers).
### return
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `return` код [текст];
`return` код URL;
`return` URL; |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location, if |
Завершает обработку и возвращает клиенту указанный `код`. Нестандартный
код 444 закрывает соединение без передачи заголовка ответа.
Можно задать либо URL перенаправления (для кодов 301, 302, 303, 307 и 308) либо текст тела ответа (для остальных кодов). В тексте тела ответа и URL перенаправления можно использовать переменные. Как частный случай, URL перенаправления может быть задан как URI, локальный для данного сервера, при этом полный URL перенаправления формируется согласно схеме запроса ($scheme) и директивам [server_name_in_redirect](https://angie.software//angie/docs/configuration/modules/http/index.md#server-name-in-redirect) и [port_in_redirect](https://angie.software//angie/docs/configuration/modules/http/index.md#port-in-redirect).
Кроме того, в качестве единственного параметра можно указать URL для временного перенаправления с кодом 302. Такой параметр должен начинаться со строк `http://`, `https://` или "$scheme". В URL можно использовать переменные.
См. также директиву [error_page](https://angie.software//angie/docs/configuration/modules/http/index.md#error-page).
### rewrite
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `rewrite` regex замена [флаг]; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location, if |
Если указанное регулярное выражение regex соответствует URI запроса, URI
изменяется в соответствии со строкой замены. Директивы `rewrite`
выполняются последовательно, в порядке их следования в конфигурационном файле. С
помощью флага можно прекратить дальнейшую обработку директив. Если строка
замены начинается с `http://`, `https://` или `$scheme`, то
обработка завершается и клиенту возвращается перенаправление.
Необязательный параметр флаг может быть задан одним из следующих значений:
| `last` | завершает обработку текущего набора директив модуля `http_rewrite`, после чего ищется новый `location`, соответствующий измененному URI; |
|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| `break` | завершает обработку текущего набора директив модуля `http_rewrite` аналогично директиве `break`; |
| `redirect` | возвращает временное перенаправление с кодом 302; используется, если
строка `замены` не начинается с `http://`, `https://` или
"$scheme"; |
| `permanent` | возвращает постоянное перенаправление с кодом 301. |
Полный URL перенаправлений формируется согласно схеме запроса ($scheme) и директив [server_name_in_redirect](https://angie.software//angie/docs/configuration/modules/http/index.md#server-name-in-redirect) и [port_in_redirect](https://angie.software//angie/docs/configuration/modules/http/index.md#port-in-redirect).
Пример:
```nginx
server {
# ...
rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last;
rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra last;
return 403;
# ...
}
```
Если же эти директивы поместить в location "/download/", то нужно заменить флаг `last` на `break`, иначе Angie сделает 10 циклов и вернет ошибку 500:
```nginx
location /download/ {
rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra break;
return 403;
}
```
Если в строке `замены` указаны новые аргументы запроса, то предыдущие
аргументы запроса добавляются после них. Если такое поведение нежелательно,
можно отказаться от этого добавления, указав в конце строки замены знак вопроса,
например:
```nginx
rewrite ^/users/(.*)$ /show?user=$1? last;
```
Если в регулярном выражении встречаются символы "}" или ";", то все выражение следует заключить в одинарные или двойные кавычки.
### rewrite_log
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `rewrite_log` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `rewrite_log off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if |
Разрешает или запрещает записывать в [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log) на уровне `notice` результаты обработки директив модуля `http_rewrite`.
### set
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `set` $переменная значение; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location, if |
Устанавливает значение указанной переменной. В качестве значения можно использовать текст, переменные и их комбинации.
### uninitialized_variable_warn
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uninitialized_variable_warn` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| По умолчанию | `uninitialized_variable_warn on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if |
Определяет, нужно ли писать в лог предупреждения о неинициализированных переменных.
## Внутреннее устройство
Директивы модуля `http_rewrite` компилируются на стадии конфигурации во внутренние инструкции, интерпретируемые во время обработки запроса. Интерпретатор представляет из себя простую стековую виртуальную машину.
Например, директивы
```nginx
location /download/ {
if ($forbidden) {
return 403;
}
if ($slow) {
limit_rate 10k;
}
rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
}
```
будут транслированы в такие инструкции:
```console
переменная $forbidden
проверка на ноль
возврат 403
завершение всего кода
переменная $slow
проверка на ноль
проверка регулярного выражения
копирование "/"
копирование $1
копирование "/mp3/"
копирование $2
копирование ".mp3"
завершение регулярного выражения
завершение всего кода
```
Обратите внимание, что инструкций для директивы [limit_rate](https://angie.software//angie/docs/configuration/modules/http/index.md#limit-rate) нет, поскольку она не имеет отношения к модулю `http_rewrite`. Для блока `if` создается отдельная конфигурация. Если условие истинно, запрос получает эту конфигурацию, и в ней `limit_rate` равен 10k.
Директиву
```nginx
rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
```
можно сделать на одну инструкцию меньше, если в регулярном выражении перенести первую косую черту внутрь скобок:
```nginx
rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
```
Тогда соответствующие инструкции будут выглядеть так:
```console
проверка регулярного выражения
копирование $1
копирование "/mp3/"
копирование $2
копирование ".mp3"
завершение регулярного выражения
завершение всего кода
```
# https://angie.software/angie/docs/configuration/modules/http/http_scgi.md
# SCGI
Позволяет передавать запросы SCGI-серверу.
## Пример конфигурации
```nginx
location / {
include scgi_params;
scgi_pass localhost:9000;
}
```
## Директивы
### scgi_bind
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_bind` адрес [`transparent`] | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает локальный IP-адрес с необязательным портом, который будет использоваться в исходящих соединениях с SCGI-сервером. В значении параметра допустимо использование переменных. Специальное значение `off` отменяет действие унаследованной с предыдущего уровня конфигурации директивы scgi_bind, позволяя системе самостоятельно выбирать локальный IP-адрес и порт.
Параметр `transparent` позволяет задать нелокальный IP-адрес, который будет использоваться в исходящих соединениях с SCGI-сервером, например, реальный IP-адрес клиента:
```nginx
scgi_bind $remote_addr transparent;
```
Для работы параметра обычно требуется запустить рабочие процессы Angie с привилегиями [суперпользователя](https://angie.software//angie/docs/configuration/modules/core.md#user). В Linux это не требуется, так как если указан параметр transparent, то рабочие процессы наследуют capability CAP_NET_RAW из главного процесса.
#### NOTE
Необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с SCGI-сервера.
### scgi_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_buffer_size` размер; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `scgi_buffer_size 4k|8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает размер буфера, в который будет читаться первая часть ответа, получаемого от SCGI-сервера. В этой части ответа обычно находится небольшой заголовок ответа. По умолчанию размер одного буфера равен размеру страницы памяти. В зависимости от платформы это или 4K, или 8K, однако его можно сделать меньше.
### scgi_buffering
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_buffering` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `scgi_buffering on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает использовать буферизацию ответов SCGI-сервера.
| `on` | Angie принимает ответ SCGI-сервера как можно быстрее, сохраняя его в
буферы, заданные директивами [scgi_buffer_size](#scgi-buffer-size) и
[scgi_buffers](#scgi-buffers). Отправка клиенту при этом выполняется параллельно:
заполненные буферы передаются на отправку, но
суммарно не более значения [scgi_busy_buffers_size](#scgi-busy-buffers-size). Если буфер
заполнен не полностью, то на отправку он не передается, если только это
не последние данные ответа. Поэтому для моментальной передачи каждых
нескольких байт режим буферизированного чтения не подходит. Если ответ
не вмещается целиком в память, то его часть может быть записана на диск
во [временный файл](#scgi-temp-path). Запись во временные файлы
контролируется директивами [scgi_max_temp_file_size](#scgi-max-temp-file-size) и
[scgi_temp_file_write_size](#scgi-temp-file-write-size). |
|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | Ответ передается клиенту сразу же по мере его поступления. Angie
работает в цикле «прочитал — отправил» и не ждет, пока буфер заполнится
целиком: например, прочитанные 10 байт из буфера 4К будут сразу
отправлены клиенту. При этом если весь ответ умещается в буфер, Angie
может прочитать его целиком. Максимальный размер данных, который Angie
может принять от сервера за один раз, задается директивой
[scgi_buffer_size](#scgi-buffer-size). При `off` не работает
[scgi_limit_rate](#scgi-limit-rate). |
Буферизация может быть также включена или выключена путем передачи значения "yes" или "no" в поле `X-Accel-Buffering` заголовка ответа. Эту возможность можно запретить с помощью директивы [scgi_ignore_headers](#scgi-ignore-headers).
### scgi_buffers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_buffers` число размер; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `scgi_buffers 8 4k | 8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число и размер буферов для одного соединения, в которые будет читаться ответ, получаемый от SCGI-сервера.
По умолчанию размер одного буфера равен размеру страницы. В зависимости от платформы это или 4K, или 8K.
### scgi_busy_buffers_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_busy_buffers_size` размер; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `scgi_busy_buffers_size 8k | 16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
При включенной [буферизации](#scgi-buffering) ответов SCGI-сервера, ограничивает суммарный размер буферов, которые могут быть заняты для отправки ответа клиенту, пока ответ еще не прочитан целиком. Оставшиеся буферы тем временем могут использоваться для чтения ответа и, при необходимости, буферизации части ответа во временный файл.
По умолчанию размер ограничен величиной двух буферов, заданных директивами [scgi_buffer_size](#scgi-buffer-size) и [scgi_buffers](#scgi-buffers).
### scgi_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache` зона | `off`; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `scgi_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает зону разделяемой памяти, используемой для кэширования. Одна и та же зона может использоваться в нескольких местах. В значении параметра можно использовать переменные.
| `off` | запрещает кэширование, унаследованное с предыдущего уровня конфигурации. |
|---------|----------------------------------------------------------------------------|
### scgi_cache_background_update
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_background_update` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| По умолчанию | `scgi_cache_background_update off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запустить фоновый подзапрос для обновления просроченного элемента кэша, в то время как клиенту возвращается устаревший кэшированный ответ.
#### WARNING
Использование устаревшего кэшированного ответа в момент его обновления должно быть [разрешено](#scgi-cache-use-stale-updating).
### scgi_cache_bypass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_bypass` ...; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает условия, при которых ответ не будет браться из кэша. Если значение хотя бы одного из строковых параметров непустое и не равно "0", то ответ не берется из кэша:
```nginx
scgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
scgi_cache_bypass $http_pragma $http_authorization;
```
Можно использовать совместно с директивой [scgi_no_cache](#scgi-no-cache).
### scgi_cache_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_key` строка; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает ключ для кэширования, например,
```nginx
scgi_cache_key localhost:9000$request_uri;
```
### scgi_cache_lock
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_lock` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `scgi_cache_lock off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если включено, одновременно только одному запросу будет позволено заполнить новый элемент кэша, идентифицируемый согласно директиве [scgi_cache_key](#scgi-cache-key), передав запрос на SCGI-сервер. Остальные запросы этого же элемента будут либо ожидать появления ответа в кэше, либо освобождения блокировки этого элемента, в течение времени, заданного директивой [scgi_cache_lock_timeout](#scgi-cache-lock-timeout).
### scgi_cache_lock_age
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_lock_age` время; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `scgi_cache_lock_age 5s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если последний запрос, переданный на SCGI-сервер для заполнения нового элемента кэша, не завершился за указанное время, на SCGI-сервер может быть передан еще один запрос.
### scgi_cache_lock_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_lock_timeout` время; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `scgi_cache_lock_timeout 5s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут для [scgi_cache_lock](#scgi-cache-lock). По истечении указанного времени запрос будет передан на SCGI-сервер, однако ответ не будет кэширован.
### scgi_cache_max_range_offset
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_max_range_offset` число; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает смещение в байтах для запросов с указанием диапазона запрашиваемых байт (byte-range requests). Если диапазон находится за указанным смещением, range-запрос будет передан на SCGI-сервер и ответ не будет кэширован.
### scgi_cache_methods
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_methods` `GET` | `HEAD` | `POST` ...; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------|
| По умолчанию | `scgi_cache_methods GET HEAD;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если метод запроса клиента указан в этой директиве, то ответ будет кэширован. Методы "GET" и "HEAD" всегда добавляются в список, но тем не менее рекомендуется перечислять их явно. См. также директиву [scgi_no_cache](#scgi-no-cache).
### scgi_cache_min_uses
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_min_uses` число; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `scgi_cache_min_uses 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число запросов, после которого ответ будет кэширован.
#### WARNING
Метаданные кэша хранятся в разделяемой памяти. Ручное удаление файлов кэша не
сбрасывает счетчики и может привести к непредсказуемому поведению. Для
полного сброса остановите сервер, удалите директорию кэша и запустите снова.
#### NOTE
Сторонние модули очистки кэша (например, [Cache Purge](https://angie.software//angie/docs/installation/external-modules/cache-purge.md#external-cache-purge)) удаляют только
файлы, но не сбрасывают счетчик scgi_cache_min_uses. Директива
предназначена для защиты кэша от загрязнения редкими запросами, и сброс
счетчика при очистке может негативно повлиять на производительность.
### scgi_cache_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_path` путь [`levels=`уровни] [`use_temp_path=``on` | `off`] `keys_zone=`имя:размер [`inactive=`время] [`max_size=`размер] [`min_free=`размер] [`manager_files=`число] [`manager_sleep=`время] [`manager_threshold=`время] [`loader_files=`число] [`loader_sleep=`время] [`loader_threshold=`время]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает путь и другие параметры кэша. Данные кэша хранятся в файлах. Именем файла в кэше является результат функции MD5 от [ключа кэширования](#scgi-cache-key).
Параметр `levels` задает уровни иерархии кэша: можно задать от 1 до 3 уровней, на каждом уровне допускаются значения 1 или 2.
Например, при использовании
```nginx
scgi_cache_path /data/angie/cache levels=1:2 keys_zone=one:10m;
```
имена файлов в кэше будут такого вида:
```nginx
/data/angie/cache/c/29/b7f54b2df7773722d382f4809d65029c
```
Кэшируемый ответ сначала записывается во временный файл, а потом этот файл переименовывается. Временные файлы и кэш могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешевой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если кэш будет находиться на той же файловой системе, что и каталог с временными файлами.
Какой из каталогов будет использоваться для временных файлов, определяется параметром `use_temp_path`.
| `on` | Если параметр не задан или установлен в значение "on", будет использоваться каталог, задаваемый директивой [scgi_temp_path](#scgi-temp-path) для данного location |
|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | временные файлы будут располагаться непосредственно в каталоге кэша |
Кроме того, все активные ключи и информация о данных хранятся в зоне разделяемой памяти, имя и размер которой задаются параметром `keys_zone`. Зоны размером в 1 мегабайт достаточно для хранения около 8 тысяч ключей. Метаданные кэша хранятся в разделяемой памяти.
Если к данным кэша не обращаются в течение времени, заданного параметром `inactive`, то данные удаляются, независимо от их свежести.
По умолчанию `inactive` равен 10 минутам.
Специальный процесс **менеджера кэша** следит за максимальным размером кэша, а также за минимальным объемом свободного места на файловой системе с кэшем, и удаляет наименее востребованные данные при превышении максимального размера кэша или недостаточном объеме свободного места. Удаление данных происходит итерациями.
| `max_size` | максимальное пороговое значение размера кэша |
|---------------------|--------------------------------------------------------------------------------------------------------|
| `min_free` | минимальное пороговое значение объема свободного места на файловой системе с кэшем |
| `manager_files` | максимальное количество удаляемых элементов кэша за одну итерацию
По умолчанию: `100` |
| `manager_threshold` | ограничивает время работы одной итерации
По умолчанию: `200` миллисекунд |
| `manager_sleep` | время, в течение которого выдерживается пауза между итерациями
По умолчанию: `50` миллисекунд |
Через минуту после старта Angie активируется специальный процесс **загрузчика кэша**, который загружает в зону кэша информацию о ранее кэшированных данных, хранящихся на файловой системе. Загрузка также происходит итерациями.
| `loader_files` | максимальное количество элементов кэша к загрузке в одну итерацию
По умолчанию: `100` |
|--------------------|--------------------------------------------------------------------------------------------------------|
| `loader_threshold` | ограничивает время работы одной итерации
По умолчанию: `200` миллисекунд |
| `loader_sleep` | время, в течение которого выдерживается пауза между итерациями
По умолчанию: `50` миллисекунд |
### scgi_cache_revalidate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_revalidate` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `scgi_cache_revalidate off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает ревалидацию просроченных элементов кэша при помощи условных запросов с полями заголовка `If-Modified-Since` и `If-None-Match` .
### scgi_cache_use_stale
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_use_stale` `error` | `timeout` | `invalid_header` | `updating` | `http_500` | `http_503` | `http_403` | `http_404` | `http_429` | `off` ...; |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `scgi_cache_use_stale off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, в каких случаях можно использовать устаревший кэшированный ответ. Параметры директивы совпадают с параметрами директивы [scgi_next_upstream](#scgi-next-upstream).
| `error` | Позволяет использовать устаревший кэшированный ответ при невозможности выбора SCGI-сервера для обработки запроса. |
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `updating` | Дополнительный параметр, разрешает использовать устаревший кэшированный ответ, если на данный момент он уже обновляется. Это позволяет минимизировать число обращений к SCGI-серверам при обновлении кэшированных данных. |
Использование устаревшего кэшированного ответа может также быть разрешено непосредственно в заголовке ответа на определенное количество секунд после того, как ответ устарел:
* Расширение [stale-while-revalidate](https://datatracker.ietf.org/doc/html/rfc5861#section-3) поля заголовка `Cache-Control` разрешает использовать устаревший кэшированный ответ, если на данный момент он уже обновляется.
* Расширение [stale-if-error](https://datatracker.ietf.org/doc/html/rfc5861#section-4) поля заголовка `Cache-Control` разрешает использовать устаревший кэшированный ответ в случае ошибки.
#### NOTE
Такой способ менее приоритетен, чем задание параметров директивы.
Чтобы минимизировать число обращений к SCGI-серверам при заполнении нового элемента кэша, можно воспользоваться директивой [scgi_cache_lock](#scgi-cache-lock).
### scgi_cache_valid
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_valid` [код ...] время; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает время кэширования для разных кодов ответа. Например, директивы
```nginx
scgi_cache_valid 200 302 10m;
scgi_cache_valid 404 1m;
```
задают время кэширования 10 минут для ответов с кодами 200 и 302 и 1 минуту для ответов с кодом 404.
Если указано только время кэширования,
```nginx
scgi_cache_valid 5m;
```
то кэшируются только ответы 200, 301 и 302.
Кроме того, можно кэшировать любые ответы с помощью параметра `any`:
```nginx
scgi_cache_valid 200 302 10m;
scgi_cache_valid 301 1h;
scgi_cache_valid any 1m;
```
#### NOTE
Параметры кэширования могут также быть заданы непосредственно в заголовке ответа. Такой способ приоритетнее, чем задание времени кэширования с помощью директивы.
* Поле заголовка `X-Accel-Expires` задает время кэширования ответа в секундах. Значение 0 запрещает кэшировать ответ. Если значение начинается с префикса @, оно задает абсолютное время в секундах с начала эпохи, до которого ответ может быть кэширован.
* Если в заголовке нет поля `X-Accel-Expires`, параметры кэширования определяются по полям заголовка `Expires` или `Cache-Control`.
* Ответ, в заголовке которого есть поле `Set-Cookie`, не будет кэшироваться.
* Ответ, в заголовке которого есть поле `Vary` со специальным значением "\*", не будет кэшироваться. Ответ, в заголовке которого есть поле `Vary` с другим значением, будет кэширован с учетом соответствующих полей заголовка запроса.
Обработка одного или более из этих полей заголовка может быть отключена при помощи директивы [scgi_ignore_headers](#scgi-ignore-headers).
### scgi_connect_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_connect_timeout` время; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `scgi_connect_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут для установления соединения с SCGI-сервером. Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.
### scgi_connection_drop
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_connection_drop` время | `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| По умолчанию | `scgi_connection_drop off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Настраивает завершение всех соединений с проксируемым сервером,
если он был удален из группы или помечен как постоянно недоступный
в результате процесса [reresolve](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve)
или [команды API](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods) `DELETE`.
Соединение завершается, когда обрабатывается следующее событие чтения или записи
для клиента или проксируемого сервера.
Установка времени включает [таймаут](https://angie.software//angie/docs/configuration/configfile.md#syntax) до завершения соединения;
при выборе значения `on` соединения завершаются немедленно.
### scgi_force_ranges
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_force_ranges` `off`; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `scgi_force_ranges off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Включает поддержку диапазонов запрашиваемых байт (byte-range) для кэшированных и некэшированных ответов SCGI-сервера вне зависимости от наличия поля `Accept-Ranges` в заголовках этих ответов.
### scgi_hide_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_hide_header` поле; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
По умолчанию Angie не передает клиенту поля заголовка `Status` и `X-Accel-...` из ответа SCGI-сервера. Директива scgi_hide_header задает дополнительные поля, которые не будут передаваться. Если же передачу полей нужно разрешить, можно воспользоваться директивой [scgi_pass_header](#scgi-pass-header).
### scgi_ignore_client_abort
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_ignore_client_abort` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `scgi_ignore_client_abort off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, закрывать ли соединение с SCGI-сервером в случае, если клиент закрыл соединение, не дождавшись ответа.
### scgi_ignore_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_ignore_headers` поле ...; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Запрещает обработку некоторых полей заголовка из ответа SCGI-сервера. В директиве можно указать поля `X-Accel-Redirect`, `X-Accel-Expires`, `X-Accel-Limit-Rate`, `X-Accel-Buffering`, `X-Accel-Charset`, `Expires`, `Cache-Control`, `Set-Cookie` и `Vary`.
Если не запрещено, обработка этих полей заголовка заключается в следующем:
* `X-Accel-Expires`, `Expires`, `Cache-Control`, `Set-Cookie` и `Vary` задают [параметры кэширования](#scgi-cache-valid) ответа;
* `X-Accel-Redirect` производит [внутреннее перенаправление](https://angie.software//angie/docs/configuration/modules/http/index.md#internal) на указанный URI;
* `X-Accel-Limit-Rate` задает [ограничение скорости](https://angie.software//angie/docs/configuration/modules/http/index.md#limit-rate) передачи ответа клиенту;
* `X-Accel-Buffering` включает или выключает [буферизацию](#scgi-buffering) ответа;
* `X-Accel-Charset` задает желаемую [кодировку](https://angie.software//angie/docs/configuration/modules/http/http_charset.md#id3) ответа.
### scgi_intercept_errors
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_intercept_errors` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `scgi_intercept_errors off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, передавать ли клиенту ответы SCGI-сервера с кодом больше либо равным 300, или же перехватывать их и перенаправлять на обработку Angie с помощью директивы [error_page](https://angie.software//angie/docs/configuration/modules/http/index.md#error-page).
### scgi_limit_rate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_limit_rate` скорость; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `scgi_limit_rate 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает скорость чтения ответа от SCGI-сервера.
Скорость задается в байтах в секунду; можно использовать переменные.
| `0` | отключает ограничение скорости |
|-------|----------------------------------|
#### NOTE
Ограничение устанавливается на запрос, поэтому, если Angie одновременно откроет два соединения к SCGI-серверу, суммарная скорость будет вдвое выше заданного ограничения. Ограничение работает только в случае, если включена [буферизация](#scgi-buffering) ответов SCGI-сервера.
### scgi_max_temp_file_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_max_temp_file_size` размер; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `scgi_max_temp_file_size 1024m;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если включена [буферизация](#scgi-buffering) ответов SCGI-сервера, и ответ не вмещается целиком в буферы, заданные директивами [scgi_buffer_size](#scgi-buffer-size) и [scgi_buffers](#scgi-buffers), часть ответа может быть записана во временный файл. Эта директива задает максимальный размер временного файла. Размер данных, сбрасываемых во временный файл за один раз, задается директивой [scgi_temp_file_write_size](#scgi-temp-file-write-size).
| `0` | отключает возможность буферизации ответов во временные файлы |
|-------|----------------------------------------------------------------|
#### NOTE
Данное ограничение не распространяется на ответы, которые будут [кэшированы](#scgi-cache) или сохранены [на диске](#scgi-store).
### scgi_next_upstream
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_next_upstream` `error` | `timeout` | `invalid_header` | `http_500` | `http_503` | `http_403` | `http_404` | `http_429` | `non_idempotent` | `off` ...; |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `scgi_next_upstream error timeout;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, в каких случаях запрос будет передан следующему серверу:
| `error` | произошла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `timeout` | произошел таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
| `invalid_header` | сервер вернул пустой или неверный ответ; |
| `http_500` | сервер вернул ответ с кодом 500; |
| `http_503` | сервер вернул ответ с кодом 503; |
| `http_403` | сервер вернул ответ с кодом 403; |
| `http_404` | сервер вернул ответ с кодом 404; |
| `http_429` | сервер вернул ответ с кодом 429; |
| `non_idempotent` | обычно запросы с [неидемпотентным](https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2) методом (POST, LOCK, PATCH) не передаются на другой сервер, если запрос серверу группы уже был отправлен; включение параметра явно разрешает повторять подобные запросы; |
| `off` | запрещает передачу запроса следующему серверу. |
#### NOTE
Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту еще ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа клиенту, то действие директивы на такой запрос не распространяется.
Директива также определяет, что считается [неудачной попыткой](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) работы с сервером.
| `error`
`timeout`
`invalid_header` | всегда считаются неудачными попытками, даже если они не указаны в директиве |
|--------------------------------------------------------|-------------------------------------------------------------------------------|
| `http_500`
`http_503`
`http_429` | считаются неудачными попытками, только если они указаны в директиве |
| `http_403`
`http_404` | никогда не считаются неудачными попытками |
Передача запроса следующему серверу может быть ограничена по [количеству попыток](#scgi-next-upstream-tries) и по [времени](#scgi-next-upstream-timeout).
### scgi_next_upstream_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_next_upstream_timeout` время; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `scgi_next_upstream_timeout 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает время, в течение которого возможна передача запроса [следующему](#scgi-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### scgi_next_upstream_tries
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_next_upstream_tries` число; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `scgi_next_upstream_tries 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает число допустимых попыток для передачи запроса [следующему](#scgi-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### scgi_no_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_no_cache` строка ...; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает условия, при которых ответ не будет сохраняться в кэш. Если значение хотя бы одного из строковых параметров непустое и не равно "0", то ответ не будет сохранен:
```nginx
scgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
scgi_no_cache $http_pragma $http_authorization;
```
Можно использовать совместно с директивой [scgi_cache_bypass](#scgi-cache-bypass).
### scgi_param
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_param` параметр значение [`if_not_empty`]; |
|------------------------------------------------------------------------------------------|----------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает параметр, который будет передаваться SCGI-серверу. В качестве значения можно использовать текст, переменные и их комбинации. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы SCGI-param.
Стандартные [переменные окружения CGI](https://datatracker.ietf.org/doc/html/rfc3875#section-4.1) должны передаваться как заголовки SCGI, см. файл scgi_params из дистрибутива:
```nginx
location / {
include scgi_params;
# ...
}
```
В стандартном файле `scgi_params` параметр `REQUEST_METHOD`
задается как `$upstream_request_method`.
Если директива указана с `if_not_empty`, то такой параметр с пустым значением передаваться на сервер не будет:
```nginx
scgi_param HTTPS $https if_not_empty;
```
### scgi_pass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_pass` uri; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location, if в location |
Задает адрес SCGI-сервера. Адрес может быть указан в виде доменного имени или IP-адреса, и порта:
```nginx
scgi_pass localhost:9000;
```
или в виде пути UNIX-сокета:
```nginx
scgi_pass unix:/tmp/scgi.socket;
```
Если доменному имени соответствует несколько адресов, то все они будут использоваться по очереди (round-robin). Кроме того, в качестве адреса можно указать [группу серверов](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).
В значении параметра можно использовать переменные. В этом случае, если адрес указан в виде доменного имени, имя ищется среди описанных групп серверов и если не найдено, то определяется с помощью [resolver](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver)'а.
#### NOTE
Если `scgi_pass` стоит в `location` с косой чертой в конце префикса
(например, `location /name/`),
и при этом в директиве [auto_redirect](https://angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) указано `default`,
запросы без косой черты в конце будут перенаправляться (`/name -> /name/`).
### scgi_pass_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_pass_header` поле ...; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает передавать от SCGI-сервера клиенту [запрещенные для передачи](#scgi-hide-header) поля заголовка.
### scgi_pass_request_body
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_pass_request_body` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `scgi_pass_request_body on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запретить передачу исходного тела запроса на SCGI-сервер. См. также директиву [scgi_pass_request_headers](#scgi-pass-request-headers).
### scgi_pass_request_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_pass_request_headers` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | `scgi_pass_request_headers on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запретить передачу полей заголовка исходного запроса на SCGI-сервер. См. также директиву [scgi_pass_request_body](#scgi-pass-request-body).
### scgi_read_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_read_timeout` время; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `scgi_read_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при чтении ответа SCGI-сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени SCGI-сервер ничего не передаст, соединение закрывается.
### scgi_request_buffering
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_request_buffering` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `scgi_request_buffering on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает использовать буферизацию тела запроса клиента.
| `on` | тело запроса полностью [читается](https://angie.software//angie/docs/configuration/modules/http/index.md#client-body-buffer-size) от клиента перед отправкой запроса на SCGI-сервер. |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | тело запроса отправляется на SCGI-сервер сразу же по мере его поступления. В этом случае запрос не может быть передан [следующему серверу](#scgi-next-upstream), если Angie уже начал отправку тела запроса. |
Если для отправки тела исходного запроса используется HTTP/1.1 и передача данных частями (chunked transfer encoding), то тело запроса буферизуется независимо от значения директивы.
### scgi_send_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_send_timeout` время; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `scgi_send_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при передаче запроса SCGI-серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени SCGI-сервер не примет новых данных, соединение закрывается.
### scgi_socket_keepalive
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_socket_keepalive` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `scgi_socket_keepalive off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Конфигурирует поведение "TCP keepalive" для исходящих соединений к SCGI-серверу.
| `""` | По умолчанию для сокета действуют настройки операционной системы. |
|--------|---------------------------------------------------------------------|
| `on` | для сокета включается параметр SO_KEEPALIVE |
### scgi_store
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_store` `on` | `off` | строка; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `scgi_store off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает сохранение на диск файлов.
| `on` | сохраняет файлы в соответствии с путями, указанными в директивах [alias](https://angie.software//angie/docs/configuration/modules/http/index.md#alias) или [root](https://angie.software//angie/docs/configuration/modules/http/index.md#root) |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | запрещает сохранение файлов |
Имя файла можно задать явно с помощью `строки` с переменными:
```nginx
scgi_store /data/www$original_uri;
```
Время изменения файлов выставляется согласно полученному полю `Last-Modified` в заголовке ответа. Ответ сначала записывается во временный файл, а потом этот файл переименовывается. Временный файл и постоянное место хранения ответа могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешевой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой системе, что и каталог с временными файлами, задаваемый директивой [scgi_temp_path](#scgi-temp-path) для данного location.
Директиву можно использовать для создания локальных копий статических неизменяемых файлов:
```nginx
location /images/ {
root /data/www;
error_page 404 = /fetch$uri;
}
location /fetch/ {
internal;
scgi_pass backend:9000;
# ...
scgi_store on;
scgi_store_access user:rw group:rw all:r;
scgi_temp_path /data/temp;
alias /data/www/;
}
```
### scgi_store_access
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_store_access` пользователи:права ...; |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| По умолчанию | `scgi_store_access user:rw;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает права доступа для создаваемых файлов и каталогов, например,
```nginx
scgi_store_access user:rw group:rw all:r;
```
Если заданы какие-либо права для group или all, то права для user указывать необязательно:
```nginx
scgi_store_access group:rw all:r;
```
### scgi_temp_file_write_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_temp_file_write_size` размер; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `scgi_temp_file_write_size 8k|16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает размер данных, сбрасываемых во временный файл за один раз, при включенной буферизации ответов SCGI-сервера во временные файлы. По умолчанию размер ограничен двумя буферами, заданными директивами [scgi_buffer_size](#scgi-buffer-size) и [scgi_buffers](#scgi-buffers). Максимальный размер временного файла задается директивой [scgi_max_temp_file_size](#scgi-max-temp-file-size).
### scgi_temp_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_temp_path` путь [уровень1 [уровень2 [уровень3]]]\`; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `scgi_temp_path scgi_temp;`
(путь зависит от [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-scgi-temp-path`) |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает имя каталога для хранения временных файлов с данными, полученными от SCGI-серверов. В каталоге может использоваться иерархия подкаталогов до трех уровней. Например, при такой конфигурации
```nginx
scgi_temp_path /spool/angie/scgi_temp 1 2;
```
временный файл будет следующего вида:
```nginx
/spool/angie/scgi_temp/7/45/00000123457
```
См. также параметр `use_temp_path` директивы [scgi_cache_path](#scgi-cache-path).
# https://angie.software/angie/docs/configuration/modules/http/http_secure_link.md
# Secure Link
Позволяет проверять аутентичность запрашиваемых ссылок, защищать ресурсы от несанкционированного доступа, а также ограничивать срок действия ссылок.
Правильность запрашиваемой ссылки проверяется сравнением переданного в запросе значения контрольной суммы со значением, вычисляемым для запроса. Если ссылка имеет ограниченный срок действия и он истек, ссылка считается устаревшей. Результат этих проверок делается доступным в переменной [$secure_link](#v-secure-link).
Модуль реализует два альтернативных режима работы. В первом режиме, который включается директивой [secure_link_secret](#secure-link-secret), можно проверить аутентичность запрашиваемых ссылок и защитить их от несанкционированного доступа. Второй режим включается директивами [secure_link](#id2) и [secure_link_md5](#secure-link-md5), и позволяет также ограничить срок действия ссылок.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_secure_link_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
## Директивы
### secure_link
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `secure_link` выражение; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает строку с переменными, из которой будет выделено значение контрольной суммы и время действия ссылки.
Используемые в выражении переменные обычно связаны с запросом; см. [пример](#secure-link-md5) ниже.
Выделенное из строки значение контрольной суммы сравнивается со значением MD5-хэша, вычисляемым для выражения, заданного директивой [secure_link_md5](#secure-link-md5).
Если контрольные суммы не совпадают, значением переменной [$secure_link](#v-secure-link) становится пустая строка. Если контрольные суммы совпадают, проверяется время действия ссылки.
Если срок действия ссылки задан и истек, переменная [$secure_link](#v-secure-link) получает значение `0`. В противном случае она получает значение `1`. Значение MD5-хэша передается в запросе закодированным в base64url.
Если ссылка имеет ограниченный срок действия, время ее действия задается в секундах с начала эпохи (1 января 1970 года 00:00:00 GMT). Значение указывается в выражении после MD5-хэша и отделяется от него запятой. Время действия ссылки, переданное в запросе, делается доступным в переменной [$secure_link_expires](#v-secure-link-expires) для использования в директиве [secure_link_md5](#secure-link-md5). Если время действия ссылки не задано, ссылка имеет неограниченный срок действия.
### secure_link_md5
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `secure_link_md5` выражение; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает выражение, для которого считается значение MD5-хэша, сравниваемое с переданным в запросе.
Выражение должно содержать защищаемую часть ссылки (ресурс) и секретную составляющую. Если ссылка имеет ограниченный срок действия, выражение также должно содержать [$secure_link_expires](#v-secure-link-expires).
Для предотвращения несанкционированного доступа выражение может содержать информацию о клиенте, например, его адрес и версию браузера.
Пример:
```nginx
location /s/ {
secure_link $arg_md5,$arg_expires;
secure_link_md5 "$secure_link_expires$uri$remote_addr secret";
if ($secure_link = "") {
return 403;
}
if ($secure_link = "0") {
return 410;
}
# ...
}
```
Ссылка "/s/link?md5=_e4Nc3iduzkWRm01TBBNYw&expires=2147483647" ограничивает доступ к "/s/link" для клиента с IP-адресом 127.0.0.1. Ссылка также имеет ограниченный срок действия до 19 января 2038 года (GMT).
Значение аргумента запроса md5 на UNIX можно получить так:
```console
echo -n '2147483647/s/link127.0.0.1 secret' | \
openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =
```
### secure_link_secret
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `secure_link_secret` слово; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Задает секретное слово для проверки аутентичности запрашиваемых ссылок.
Полный URI запрашиваемой ссылки выглядит так:
```console
/префикс/хэш/ссылка
```
где хэш — MD5-хэш в шестнадцатеричном виде, вычисленный для конкатенации ссылки и секретного слова, а префикс — произвольная строка без косых черт.
Если запрашиваемая ссылка проходит проверку на аутентичность, значением переменной [$secure_link](#v-secure-link) становится ссылка, выделенная из URI запроса. В противном случае значением переменной [$secure_link](#v-secure-link) становится пустая строка.
Пример:
```nginx
location /p/ {
secure_link_secret secret;
if ($secure_link = "") {
return 403;
}
rewrite ^ /secure/$secure_link;
}
location /secure/ {
internal;
}
```
По запросу "/p/5e814704a28d9bc1914ff19fa0c4a00a/link" будет выполнено внутреннее перенаправление на "/secure/link".
Значение хэша для данного примера на UNIX можно получить так:
```console
echo -n 'linksecret' | openssl md5 -hex
```
## Встроенные переменные
### `$secure_link`
Результат проверки ссылки. Конкретное значение зависит от выбранного режима работы.
### `$secure_link_expires`
Время действия ссылки, переданное в запросе. Предназначено исключительно для использования в директиве [secure_link_md5](#secure-link-md5).
# https://angie.software/angie/docs/configuration/modules/http/http_slice.md
# Slice
Фильтр, который разбивает запрос на подзапросы, каждый из которых возвращает определенный диапазон ответа. Фильтр обеспечивает более эффективное кэширование больших ответов.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_slice_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
## Пример конфигурации
```nginx
location / {
slice 1m;
proxy_cache cache;
proxy_cache_key $uri$is_args$args$slice_range;
proxy_set_header Range $slice_range;
proxy_cache_valid 200 206 1h;
proxy_pass http://localhost:8000;
}
```
В данном примере ответ разбивается на кэшируемые фрагменты размером в 1 мегабайт.
## Директивы
### slice
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `slice` размер; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | `slice 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает размер фрагмента. Нулевое значение запрещает разбиение ответов на фрагменты.
#### WARNING
Обратите внимание, что слишком низкое значение может привести к излишнему потреблению памяти и открытию большого количества файлов.
Для того, чтобы подзапрос вернул необходимый диапазон, переменная [$slice_range](#v-slice-range) должна быть передана на проксируемый сервер в качестве поля `Range` заголовка запроса. Если включено [кэширование](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache), то необходимо добавить [$slice_range](#v-slice-range) в [ключ кэширования](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-key) и [включить](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-valid) кэширование ответов с кодом 206.
## Встроенные переменные
### `$slice_range`
текущий диапазон фрагмента в формате [HTTP byte range](https://datatracker.ietf.org/doc/html/rfc7233#section-2.1), например bytes=0-1048575.
# https://angie.software/angie/docs/configuration/modules/http/http_split_clients.md
# Split Clients
Модуль генерирует переменные для A/B-тестирования, канареечных релизов
и других сценариев, которые направляют определенный процент клиентов на один
сервер или конфигурацию, а остальных — куда-то еще.
## Пример конфигурации
```nginx
http {
split_clients "${remote_addr}AAA" $variant {
0.5% .one;
2.0% .two;
* "";
}
server {
location / {
index index${variant}.html;
```
## Директивы
### split_clients
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `split_clients` строка $переменная { ... } |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Создает $переменную, хэшируя строку;
переменные в строке подставляются,
результат хэшируется,
затем по значению хэша выбирается строковое значение $переменной.
Функция хэширования использует
[MurmurHash2](https://en.wikipedia.org/wiki/MurmurHash#MurmurHash2)
(32 бит),
и весь диапазон ее значений
(с 0 по 4294967295)
сопоставляется с корзинами в порядке появления;
процентные величины определяют размер корзин.
В конце может стоять метасимвол (`*`);
хэши, не попавшие в другие корзины, сопоставляются с приданным ему значением.
Пример:
```nginx
split_clients "${remote_addr}AAA" $variant {
0.5% .one;
2.0% .two;
* "";
}
```
Здесь после подстановки в строке `$*remote_addr*AAA`
значения хэша распределяются следующим образом:
- значения от 0 до 21474835 (0,5%) дают `.one`;
- значения от 21474836 до 107374180 (2%) дают `.two`;
- значения от 107374181 до 4294967295 (все остальные) дают `""`
(пустую строку).
# https://angie.software/angie/docs/configuration/modules/http/http_ssi.md
# SSI
Фильтр, обрабатывающий команды SSI (Server Side Includes) в проходящих через него ответах.
## Пример конфигурации
```nginx
location / {
ssi on;
# ...
}
```
## Директивы
### ssi
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssi` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `ssi off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Разрешает или запрещает обработку команд SSI в ответах.
### ssi_last_modified
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssi_last_modified` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `ssi_last_modified off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет сохранить поле заголовка `Last-Modified` исходного ответа во время обработки SSI для лучшего кэширования ответов.
По умолчанию поле заголовка удаляется, так как содержимое ответа изменяется во время обработки и может содержать динамически созданные элементы или части, которые изменились независимо от исходного ответа.
### ssi_min_file_chunk
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssi_min_file_chunk` размер; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `ssi_min_file_chunk 1k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает минимальный размер частей ответа, хранящихся на диске, начиная с которого имеет смысл посылать их с помощью [sendfile](https://angie.software//angie/docs/configuration/modules/http/index.md#sendfile).
### ssi_silent_errors
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssi_silent_errors` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `ssi_silent_errors off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает не выводить строку "[an error occurred while processing the directive]", если во время обработки SSI произошла ошибка.
### ssi_types
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssi_types` mime-тип ...; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `ssi_types text/html;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает обработку команд SSI в ответах с указанными MIME-типами в дополнение к `text/html`. Специальное значение "\*" соответствует любому MIME-типу.
### ssi_value_length
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssi_value_length` длина; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `ssi_value_length 256;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает максимальную длину значений параметров в SSI-командах.
## Команды SSI
Общий формат команд SSI такой:
```html
```
Поддерживаются следующие команды:
### `block`
Описывает блок, который можно использовать как заглушку в команде include. Внутри блока могут быть другие команды SSI. Параметр команды:
#### `name`
имя блока.
Пример:
```html
заглушка
```
### `config`
Задает некоторые параметры, используемые при обработке SSI, а именно:
#### `errmsg`
строка, выводящаяся при ошибке во время обработки SSI. По умолчанию выводится такая строка:
```none
`[an error occurred while processing the directive]`
```
#### `timefmt`
строка формата, передаваемая функции `strftime()` для вывода даты и времени. По умолчанию используется такой формат:
```none
`"%A, %d-%b-%Y %H:%M:%S %Z"`
```
Для вывода времени в секундах подходит формат "%s".
### `echo`
Выводит значение переменной. Параметры команды:
#### `var`
имя переменной.
#### `encoding`
способ кодирования. Возможны три значения — `none`, `url` и `entity`. По умолчанию используется `entity`.
#### `default`
нестандартный параметр, задающий строку, которая выводится, если переменная не определена. По умолчанию выводится строка `(none)`.
Команда
```html
```
заменяет такую последовательность команд:
```html
нет
```
### `if`
Выполняет условное включение. Поддерживаются следующие команды:
```html
...
...
...
```
На данный момент поддерживается только один уровень вложенности. Параметр команды:
#### `expr`
выражение. В выражении может быть:
* проверка существования переменной:
```html
```
* сравнение переменной с текстом:
```html
```
* сравнение переменной с регулярным выражением:
```html
```
Если в text встречаются переменные, то производится подстановка их значений. В регулярном выражении можно задать позиционные и именованные группы захвата, а затем использовать их через переменные, например:
```html
```
### `include`
Включает в ответ результат другого запроса. Параметры команды:
#### `file`
задает включаемый файл, например:
```html
```
#### `virtual`
задает включаемый запрос, например:
```html
```
Несколько запросов, указанных на одной странице и обрабатываемых проксируемыми или FastCGI/uwsgi/SCGI/gRPC-серверами, работают параллельно. Если нужна последовательная обработка, следует воспользоваться параметром wait.
#### `stub`
нестандартный параметр, задающий имя блока, содержимое которого будет выведено, если тело ответа на включаемый запрос пустое или если при исполнении запроса произошла ошибка, например:
```html
```
Содержимое замещающего блока обрабатывается в контексте включаемого запроса.
#### `wait`
нестандартный параметр, указывающий, нужно ли ждать полного исполнения данного запроса, прежде чем продолжать выполнение SSI, например:
```html
```
#### `set`
нестандартный параметр, указывающий, что удачный результат выполнения запроса нужно записать в заданную переменную, например:
```html
```
Максимальный размер ответа задается директивой [subrequest_output_buffer_size](https://angie.software//angie/docs/configuration/modules/http/index.md#subrequest-output-buffer-size):
```nginx
location /remote/ {
subrequest_output_buffer_size 64k;
# ...
}
```
### `set`
Присваивает значение переменной. Параметры команды:
#### `var`
имя переменной.
#### `value`
значение переменной. Если в присваиваемом значении есть переменные, то производится подстановка их значений.
## Встроенные переменные
### `$date_local`
текущее время в локальной временной зоне. Формат задается командой config с параметром timefmt.
### `$date_gmt`
текущее время в GMT. Формат задается командой config с параметром timefmt.
# https://angie.software/angie/docs/configuration/modules/http/http_ssl.md
# SSL
Обеспечивает работу по протоколу HTTPS.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_ssl_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
#### NOTE
Для этого модуля нужна библиотека OpenSSL.
## Пример конфигурации
Для уменьшения загрузки процессора рекомендуется
* установить число [рабочих процессов](https://angie.software//angie/docs/configuration/modules/core.md#worker-processes) равным числу процессоров,
* разрешить [keep-alive](https://angie.software//angie/docs/configuration/modules/http/index.md#keepalive-timeout) соединения,
* включить [разделяемый кэш](#ssl-session-cache) сессий,
* выключить [встроенный кэш](#ssl-session-cache) сессий
* и, возможно, увеличить [время жизни](#ssl-session-timeout) сессии (по умолчанию 5 минут):
```nginx
worker_processes auto;
http {
# ...
server {
listen 443 ssl;
keepalive_timeout 70;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
ssl_certificate /usr/local/angie/conf/cert.pem;
ssl_certificate_key /usr/local/angie/conf/cert.key;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
# ...
}
```
## Директивы
### ssl_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_buffer_size` размер; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `ssl_buffer_size 16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает размер буфера, используемого при отправке данных.
По умолчанию размер буфера равен 16k, что соответствует минимальным накладным расходам при передаче больших ответов. С целью минимизации времени получения начала ответа (Time To First Byte) может быть полезно использовать меньшие значения, например:
```nginx
ssl_buffer_size 4k;
```
### ssl_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_certificate` файл; |
|------------------------------------------------------------------------------------------|---------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Указывает файл с сертификатом в формате PEM для данного виртуального сервера. Если вместе с основным сертификатом нужно указать промежуточные, то они должны находиться в этом же файле в следующем порядке: сначала основной сертификат, а затем промежуточные. В этом же файле может находиться секретный ключ в формате PEM.
Эта директива может быть указана несколько раз для загрузки сертификатов разных типов, например RSA и ECDSA:
```nginx
server {
listen 443 ssl;
server_name example.com;
ssl_certificate example.com.rsa.crt;
ssl_certificate_key example.com.rsa.key;
ssl_certificate example.com.ecdsa.crt;
ssl_certificate_key example.com.ecdsa.key;
# ...
}
```
Возможность задавать отдельные цепочки сертификатов для разных сертификатов есть только в OpenSSL 1.0.2 и выше. Для более старых версий следует указывать только одну цепочку сертификатов.
#### NOTE
В имени файла можно использовать переменные при использовании OpenSSL 1.0.2 и выше:
```nginx
ssl_certificate $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;
```
При использовании переменных сертификат загружается при каждой операции SSL-рукопожатия, что может отрицательно влиять на производительность.
Вместо файла можно указать значение `data:$переменная`, при котором
сертификат загружается из переменной без использования промежуточных файлов.
Ненадлежащее использование подобного синтаксиса может быть небезопасно, например данные секретного ключа могут попасть в [лог ошибок](https://angie.software//angie/docs/configuration/modules/core.md#error-log).
#### NOTE
> Нужно иметь в виду, что из-за ограничения протокола HTTPS для максимальной совместимости виртуальные серверы должны слушать на [разных IP-адресах](https://angie.software//angie/docs/configuration/ssl.md#https-separate-ips).
Если задан режим [ssl_ntls](#ssl-ntls), директива может принимать два аргумента
(части ключа для подписи и шифрования)
вместо одного:
```nginx
listen ... ssl;
ssl_ntls on;
# двойной сертификат NTLS
ssl_certificate sign.crt enc.crt;
ssl_certificate_key sign.key enc.key;
# можно использовать наряду с обычным сертификатом RSA
ssl_certificate rsa.crt;
ssl_certificate rsa.key;
```
### ssl_certificate_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_certificate_cache` `off`;
`ssl_certificate_cache` `max=`N [`inactive=`time] [`valid=`time]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
| Значение по умолчанию | `ssl_certificate_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Определяет кэш для хранения [SSL-сертификатов](#ssl-certificate) и [секретных ключей](#ssl-certificate-key), заданных через переменные.
Директива поддерживает следующие параметры:
- `max` — устанавливает максимальное количество элементов в кэше. При
переполнении кэша удаляются наименее недавно использованные (LRU) элементы.
- `inactive` — определяет время, после которого элемент будет удален, если
к нему не было обращений. Значение по умолчанию — 10 секунд.
- `valid` — определяет время, в течение которого элемент кэша считается
действительным и может использоваться повторно. Значение по умолчанию — 60
секунд. По истечении этого времени сертификаты перезагружаются или проходят
повторную проверку.
- `off` — отключает кэш.
Пример:
```nginx
ssl_certificate $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;
ssl_certificate_cache max=1000 inactive=20s valid=1m;
```
### ssl_certificate_compression
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_certificate_compression` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| Значение по умолчанию | `ssl_certificate_compression off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает сжатие TLS 1.3 [сертификатов сервера](https://datatracker.ietf.org/doc/html/rfc8879).
#### NOTE
Директива поддерживается при использовании OpenSSL версии 3.2 и выше; список поддерживаемых алгоритмов сжатия предоставляется библиотекой.
#### NOTE
Директива поддерживается при использовании [BoringSSL](https://boringssl.googlesource.com/boringssl/); список поддерживаемых алгоритмов сжатия включает `zlib`.
Если включен [ssl_stapling](#ssl-stapling), сжатие сертификатов отключается.
### ssl_certificate_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_certificate_key` файл; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Указывает файл с секретным ключом в формате PEM для данного виртуального сервера.
#### NOTE
В имени файла можно использовать переменные при использовании OpenSSL 1.0.2 и выше.
Вместо `файла` можно указать значение `engine:имя:id`, которое загружает
ключ с указанным id из движка OpenSSL с заданным именем.
Вместо `файла` можно указать значение `store:scheme:id`, которое
используется для загрузки ключа с указанным id и URI-схемой scheme,
зарегистрированной в OpenSSL provider, например [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).
Вместо `файла` также можно указать значение `data:$переменная`, при
котором секретный ключ загружается из переменной без использования промежуточных
файлов. При этом следует учитывать, что ненадлежащее использование подобного
синтаксиса может быть небезопасно, например данные секретного ключа могут
попасть в [лог ошибок](https://angie.software//angie/docs/configuration/modules/core.md#error-log).
> Если задан режим [ssl_ntls](#ssl-ntls), директива может принимать два аргумента
> (части ключа для подписи и шифрования)
> вместо одного:
> ```nginx
> listen ... ssl;
> ssl_ntls on;
> # двойной сертификат NTLS
> ssl_certificate sign.crt enc.crt;
> ssl_certificate_key sign.key enc.key;
> # можно использовать наряду с обычным сертификатом RSA
> ssl_certificate rsa.crt;
> ssl_certificate rsa.key;
> ```
### ssl_ciphers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ciphers` шифры; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `ssl_ciphers HIGH:!aNULL:!MD5;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Описывает разрешенные шифры. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL, например:
```nginx
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
```
Список шифров зависит от установленной версии OpenSSL.
Полный список можно посмотреть с помощью команды `openssl ciphers`.
#### WARNING
Директива `ssl_ciphers` *не* настраивает шифры для TLS 1.3 при
использовании OpenSSL. Для настройки шифров TLS 1.3 в OpenSSL используйте
директиву [ssl_conf_command](#ssl-conf-command), добавленную для расширенной
конфигурации SSL.
- В LibreSSL шифры TLS 1.3 *можно* настраивать с помощью
`ssl_ciphers`.
- В BoringSSL шифры TLS 1.3 настроить невозможно.
### ssl_client_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_client_certificate` файл; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Указывает файл с доверенными сертификатами CA в формате PEM, которые используются для [проверки](#ssl-verify-client) клиентских сертификатов и ответов OCSP, если включен [ssl_stapling](#ssl-stapling).
Список сертификатов будет отправляться клиентам. Если это нежелательно, можно воспользоваться директивой [ssl_trusted_certificate](#ssl-trusted-certificate).
### ssl_conf_command
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_conf_command` имя значение; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает произвольные [конфигурационные команды](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) OpenSSL.
#### NOTE
Директива поддерживается при использовании OpenSSL 1.0.2 и выше.
Чтобы настроить шифры TLS 1.3 в OpenSSL, используйте команду `ciphersuites`.
На одном уровне может быть указано несколько директив ssl_conf_command:
```nginx
ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;
```
Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы ssl_conf_command.
#### WARNING
Изменение настроек OpenSSL напрямую может привести к неожиданному поведению.
### ssl_crl
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_crl` файл; |
|------------------------------------------------------------------------------------------|-------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Указывает файл с отозванными сертификатами (CRL) в формате PEM, используемыми для [проверки](#ssl-verify-client) клиентских сертификатов.
### ssl_dhparam
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_dhparam` файл; |
|------------------------------------------------------------------------------------------|-----------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Указывает файл с параметрами для DHE-шифров.
#### WARNING
По умолчанию параметры не заданы, и соответственно DHE-шифры не будут использоваться.
### ssl_early_data
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_early_data` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `ssl_early_data off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает или запрещает TLS 1.3 [early data](https://datatracker.ietf.org/doc/html/rfc8446#section-2.3).
Запросы, отправленные внутри early data, могут быть подвержены [атакам повторного воспроизведения](https://datatracker.ietf.org/doc/html/rfc8470) (replay). Для защиты от подобных атак на уровне приложения необходимо использовать переменную [$ssl_early_data](#v-ssl-early-data).
```nginx
proxy_set_header Early-Data $ssl_early_data;
```
#### NOTE
Директива поддерживается при использовании OpenSSL 1.1.1 и выше или [BoringSSL](https://boringssl.googlesource.com/boringssl/).
### ssl_encrypted_hello_key
#### Versionadded
Добавлено в версии 1.11.0.
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_encrypted_hello_key` файл; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Указывает файл с приватным ключом ECH и списком ECHConfigList в формате PEM.
Директива может быть указана несколько раз.
Требуется сборка OpenSSL или BoringSSL с поддержкой Encrypted Client Hello (ECH),
иначе директива не поддерживается.
### ssl_ecdh_curve
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ecdh_curve` кривая; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `ssl_ecdh_curve auto;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает кривую для ECDHE-шифров.
#### NOTE
При использовании OpenSSL 1.0.2 и выше можно указывать несколько кривых, например:
```nginx
ssl_ecdh_curve prime256v1:secp384r1;
```
Специальное значение `auto` соответствует встроенному в библиотеку OpenSSL списку кривых для OpenSSL 1.0.2 и выше, или prime256v1 для более старых версий.
#### NOTE
При использовании OpenSSL 1.0.2 и выше директива задает список кривых, поддерживаемых сервером. Поэтому для работы ECDSA-сертификатов важно, чтобы список включал кривые, используемые в сертификатах.
### ssl_ntls
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ntls` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `ssl_ntls off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Включает серверную поддержку NTLS при использовании TLS библиотеки [TongSuo](https://github.com/Tongsuo-Project/Tongsuo)
```nginx
listen ... ssl;
ssl_ntls on;
```
#### NOTE
Angie необходимо собрать с использованием параметра конфигурации `--with-ntls`, с соответствующей SSL библиотекой с поддержкой NTLS
```default
./configure --with-openssl=../Tongsuo-8.3.0 \
--with-openssl-opt=enable-ntls \
--with-ntls
```
### ssl_ocsp
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ocsp` `on` | `off` | `leaf`; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `ssl_ocsp off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Включает проверку OCSP для цепочки клиентских сертификатов. Параметр `leaf` включает проверку только клиентского сертификата.
Для работы проверки OCSP необходимо дополнительно установить значение директивы [ssl_verify_client](#ssl-verify-client) в `on` или `optional`.
Для преобразования имени хоста OCSP-респондера в адрес необходимо дополнительно задать директиву [resolver](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver).
Пример:
```nginx
ssl_verify_client on;
ssl_ocsp on;
resolver 127.0.0.53;
```
### ssl_ocsp_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ocsp_cache` `off` | [shared:имя:размер]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| По умолчанию | `ssl_ocsp_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает имя и размер кэша, который хранит статус клиентских сертификатов для проверки OCSP-ответов. Кэш разделяется между всеми рабочими процессами. Кэш с одинаковым названием может использоваться в нескольких виртуальных серверах.
Параметр `off` запрещает использование кэша.
### ssl_ocsp_responder
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ocsp_responder` uri; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Переопределяет URI OCSP-респондера, указанный в расширении сертификата ["Authority Information Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1) для [проверки](#ssl-ocsp) клиентских сертификатов.
Поддерживаются только OCSP-респондеры на основе `http://`:
```nginx
ssl_ocsp_responder http://ocsp.example.com/;
```
### ssl_password_file
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_password_file` файл; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает файл с паролями от [секретных ключей](#ssl-certificate-key), где каждый пароль указан на отдельной строке. Пароли применяются по очереди в момент загрузки ключа.
Пример:
```nginx
http {
ssl_password_file /etc/keys/global.pass;
...
server {
server_name www1.example.com;
ssl_certificate_key /etc/keys/first.key;
}
server {
server_name www2.example.com;
# вместо файла можно указать именованный канал
ssl_password_file /etc/keys/fifo;
ssl_certificate_key /etc/keys/second.key;
}
}
```
### ssl_prefer_server_ciphers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_prefer_server_ciphers` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | `ssl_prefer_server_ciphers off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
При использовании протоколов SSLv3 и TLS устанавливает приоритет серверных шифров над клиентскими.
### ssl_protocols
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`]; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| По умолчанию | `ssl_protocols TLSv1.2 TLSv1.3;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает указанные протоколы.
#### NOTE
Параметры TLSv1.1 и TLSv1.2 работают только при использовании OpenSSL 1.0.1 и выше.
Параметр TLSv1.3 работает только при использовании OpenSSL 1.1.1 и выше.
### ssl_reject_handshake
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_reject_handshake` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `ssl_reject_handshake off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Если включено, то операции SSL-рукопожатия в блоке [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server) будут отклонены.
Например, в этой конфигурации отклоняются все операции SSL-рукопожатия с именем сервера, отличным от example.com:
```nginx
server {
listen 443 ssl default_server;
ssl_reject_handshake on;
}
server {
listen 443 ssl;
server_name example.com;
ssl_certificate example.com.crt;
ssl_certificate_key example.com.key;
}
```
### ssl_session_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_cache` `off` | `none` | [builtin[:размер]] [shared:название:размер]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| По умолчанию | `ssl_session_cache none;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает тип и размеры кэшей для хранения параметров сессий. Тип кэша может быть следующим:
| `off` | жесткое запрещение использования кэша сессий: Angie явно сообщает клиенту, что сессии не могут использоваться повторно. |
|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `none` | мягкое запрещение использования кэша сессий: Angie сообщает клиенту, что сессии могут использоваться повторно, но на самом деле не хранит параметры сессии в кэше. |
| `builtin` | встроенный в OpenSSL кэш, используется в рамках только одного рабочего процесса. Размер кэша задается в сессиях. Если размер не задан, то он равен 20480 сессиям. Использование встроенного кэша может вести к фрагментации памяти. |
| `shared` | кэш, разделяемый между всеми рабочими процессами. Размер кэша задается в байтах, в 1 мегабайт может поместиться около 4000 сессий. У каждого разделяемого кэша должно быть произвольное название. Кэш с одинаковым названием может использоваться в нескольких виртуальных серверах. Также он используется для автоматического создания, хранения и периодического обновления ключей сессионных билетов TLS, если они не указаны явно с помощью директивы [ssl_session_ticket_key](#ssl-session-ticket-key). |
Можно использовать одновременно оба типа кэша, например:
```nginx
ssl_session_cache builtin:1000 shared:SSL:10m;
```
однако использование только разделяемого кэша без встроенного должно быть более эффективным.
### ssl_session_ticket_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_ticket_key` файл; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает файл с секретным ключом, применяемым при шифровании и расшифровке сессионных билетов TLS. Директива необходима, если один и тот же ключ нужно использовать на нескольких серверах. По умолчанию используется случайно сгенерированный ключ.
Если указано несколько ключей, то только первый ключ используется для шифрования сессионных билетов TLS. Это позволяет настроить ротацию ключей, например:
```nginx
ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;
```
Файл должен содержать 80 или 48 байт случайных данных и может быть создан следующей командой:
```console
openssl rand 80 > ticket.key
```
В зависимости от размера файла для шифрования будет использоваться либо AES256 (для 80-байтных ключей), либо AES128 (для 48-байтных ключей).
### ssl_session_tickets
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_tickets` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `ssl_session_tickets on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает или запрещает возобновление сессий при помощи [сессионных билетов TLS](https://datatracker.ietf.org/doc/html/rfc5077).
### ssl_session_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_timeout` время; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `ssl_session_timeout 5m;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает время, в течение которого клиент может повторно использовать параметры сессии.
### ssl_stapling
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_stapling` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `ssl_stapling off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает или запрещает [прикрепление OCSP-ответов](https://datatracker.ietf.org/doc/html/rfc6066#section-8) сервером. Пример:
```nginx
ssl_stapling on;
resolver 127.0.0.53;
```
Для работы OCSP-прикрепления должен быть известен сертификат издателя
сертификата сервера. Если в заданном директивой [ssl_certificate](#ssl-certificate) файле не
содержится промежуточных сертификатов, то сертификат издателя сертификата
сервера следует поместить в файл, заданный директивой
[ssl_trusted_certificate](#ssl-trusted-certificate).
#### WARNING
Для преобразования имени хоста OCSP-респондера в адрес необходимо
дополнительно задать директиву [resolver](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver).
### ssl_stapling_file
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_stapling_file` файл; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Если значение задано, то вместо опроса OCSP-респондера, указанного в сертификате
сервера, ответ берется из указанного файла.
Ответ должен быть в формате DER и может быть сгенерирован командой
`openssl ocsp`.
### ssl_stapling_responder
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_stapling_responder` `uri`; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Переопределяет URI OCSP-респондера, указанный в расширении сертификата
["Authority Information Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1).
Поддерживаются только OCSP-респондеры на основе `http://`:
```nginx
ssl_stapling_responder http://ocsp.example.com/;
```
### ssl_stapling_verify
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_stapling_verify` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `ssl_stapling_verify off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает или запрещает проверку ответов OCSP сервером.
Для работоспособности проверки сертификат издателя сертификата сервера, корневой
сертификат и все промежуточные сертификаты должны быть указаны как доверенные с
помощью директивы [ssl_trusted_certificate](#ssl-trusted-certificate).
### ssl_trusted_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_trusted_certificate` файл; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает файл с доверенными сертификатами CA в формате PEM, которые используются
для [проверки](#ssl-verify-client) клиентских сертификатов и ответов OCSP,
если включен [ssl_stapling](#ssl-stapling).
В отличие от [ssl_client_certificate](#ssl-client-certificate), список этих сертификатов не будет отправляться клиентам.
### ssl_verify_client
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_verify_client` `on` | `off` | `optional` | `optional_no_ca`; |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| По умолчанию | `ssl_verify_client off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает проверку клиентских сертификатов. Результат проверки доступен через переменную [$ssl_client_verify](#v-ssl-client-verify).
| `optional` | запрашивает клиентский сертификат, и если сертификат был предоставлен, проверяет его |
|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `optional_no_ca` | запрашивает сертификат клиента, но не требует, чтобы он был подписан доверенным сертификатом CA. Это предназначено для случаев, когда фактическая проверка сертификата осуществляется внешним по отношению к Angie сервисом. |
### ssl_verify_depth
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_verify_depth` число; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `ssl_verify_depth 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Устанавливает глубину проверки в цепочке клиентских сертификатов.
## Обработка ошибок
Модуль `http_ssl` поддерживает несколько нестандартных кодов ошибок, которые можно использовать для перенаправления с помощью директивы [error_page](https://angie.software//angie/docs/configuration/modules/http/index.md#error-page):
| `495` | при проверке клиентского сертификата произошла ошибка; |
|---------|----------------------------------------------------------|
| `496` | клиент не предоставил требуемый сертификат; |
| `497` | обычный запрос был послан на порт HTTPS. |
Перенаправление делается после того, как запрос полностью разобран и доступны такие переменные, как [$request_uri](https://angie.software//angie/docs/configuration/modules/http/index.md#v-request-uri), [$uri](https://angie.software//angie/docs/configuration/modules/http/index.md#v-uri), [$args](https://angie.software//angie/docs/configuration/modules/http/index.md#v-args) и другие переменные.
## Встроенные переменные
Модуль http_ssl поддерживает встроенные переменные:
### `$ssl_alpn_protocol`
возвращает протокол, выбранный при помощи ALPN во время SSL-рукопожатия, либо пустую строку.
### `$ssl_cipher`
возвращает название используемого шифра для установленного SSL-соединения.
### `$ssl_ciphers`
возвращает список шифров, поддерживаемых клиентом. Известные шифры указаны по имени, неизвестные указаны в шестнадцатеричном виде, например:
> AES128-SHA:AES256-SHA:0x00ff
#### NOTE
Переменная полностью поддерживается при использовании OpenSSL версии 1.0.2 и выше. При использовании более старых версий переменная доступна только для новых сессий и может содержать только известные шифры.
### `$ssl_client_escaped_cert`
возвращает клиентский сертификат в формате PEM (закодирован в формате urlencode) для установленного SSL-соединения.
### `$ssl_client_fingerprint`
возвращает SHA1-отпечаток клиентского сертификата для установленного SSL-соединения.
### `$ssl_client_i_dn`
возвращает строку "issuer DN" клиентского сертификата для установленного SSL-соединения согласно [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253).
### `$ssl_client_i_dn_legacy`
возвращает строку "issuer DN" клиентского сертификата для установленного SSL-соединения.
### `$ssl_client_raw_cert`
возвращает клиентский сертификат для установленного SSL-соединения в формате PEM.
### `$ssl_client_s_dn`
возвращает строку "subject DN" клиентского сертификата для установленного SSL-соединения согласно [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253).
### `$ssl_client_s_dn_legacy`
возвращает строку "subject DN" клиентского сертификата для установленного SSL-соединения.
### `$ssl_client_serial`
возвращает серийный номер клиентского сертификата для установленного SSL-соединения.
### `$ssl_client_sigalg`
возвращает [алгоритм подписи](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) для сертификата клиента в установленном SSL-соединении.
#### NOTE
Переменная поддерживается только при использовании OpenSSL версии 3.5 и выше. При использовании более старых версий значением переменной будет пустая строка.
#### NOTE
Переменная доступна только для новых сессий.
### `$ssl_client_v_end`
возвращает дату окончания срока действия клиентского сертификата.
### `$ssl_client_v_remain`
возвращает число дней, оставшихся до истечения срока действия клиентского сертификата.
### `$ssl_client_v_start`
возвращает дату начала срока действия клиентского сертификата.
### `$ssl_client_verify`
возвращает результат проверки клиентского сертификата: `SUCCESS`, `FAILED:reason` и, если сертификат не был предоставлен, `NONE`.
### `$ssl_curve`
возвращает согласованную кривую, использованную для обмена ключами во время SSL-рукопожатия. Известные кривые указаны по имени, неизвестные указаны в шестнадцатеричном виде, например:
> prime256v1
#### NOTE
Переменная поддерживается при использовании OpenSSL версии 3.0 и выше. При использовании более старых версий значением переменной будет пустая строка.
### `$ssl_curves`
возвращает список кривых, поддерживаемых клиентом. Известные кривые указаны по имени, неизвестные указаны в шестнадцатеричном виде, например:
> 0x001d:prime256v1:secp521r1:secp384r1
#### NOTE
Переменная поддерживается при использовании OpenSSL версии 1.0.2 и выше. При использовании более старых версий значением переменной будет пустая строка.
Переменная доступна только для новых сессий.
### `$ssl_early_data`
возвращает `1`, если используется TLS 1.3 [early data](#ssl-early-data) и операция SSL-рукопожатия не завершена, иначе "".
### `$ssl_encrypted_hello`
#### Versionadded
Добавлено в версии 1.11.0.
возвращает `1`, если используется Encrypted Client Hello (ECH), иначе "".
### `$ssl_protocol`
возвращает протокол установленного SSL-соединения.
### `$ssl_server_cert_type`
принимает значения `RSA`, `DSA`, `ECDSA`, `ED448`,
`ED25519`, `SM2`, `RSA-PSS` или `unknown` в зависимости
от типа сертификата и ключа сервера.
### `$ssl_server_name`
возвращает имя сервера, запрошенное через [SNI](http://en.wikipedia.org/wiki/Server_Name_Indication).
### `$ssl_session_id`
возвращает идентификатор сессии установленного SSL-соединения.
### `$ssl_session_reused`
возвращает `r`, если сессия была использована повторно, иначе ".".
### `$ssl_sigalg`
возвращает [алгоритм подписи](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) для сертификата сервера в установленном SSL-соединении.
#### NOTE
Переменная поддерживается только при использовании OpenSSL версии 3.5 и выше. При использовании более старых версий значением переменной будет пустая строка.
#### NOTE
Переменная доступна только для новых сессий.
# https://angie.software/angie/docs/configuration/modules/http/http_stub_status.md
# Stub Status
Предоставляет доступ к базовой информации о состоянии сервера.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_stub_status_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
## Пример конфигурации
```nginx
location = /basic_status {
stub_status;
}
```
В данной конфигурации создается простая веб-страница с основной информацией о состоянии, которая может выглядеть следующим образом:
```console
Active connections: 291
server accepts handled requests
16630948 16630948 31070465
Reading: 6 Writing: 179 Waiting: 106
```
## Директивы
### stub_status
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `stub_status`; |
|------------------------------------------------------------------------------------------|------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location |
Информация о состоянии будет доступна из данного location.
## Данные
Доступна следующая информация:
### `Active connections`
Текущее число активных клиентских соединений, включая Waiting-соединения.
### `accepts`
Суммарное число принятых клиентских соединений.
### `handled`
Суммарное число обработанных соединений.
Обычно значение этого параметра совпадает с `accepts`, если не достигнуто какое-нибудь системное ограничение (например, лимит [worker_connections](https://angie.software//angie/docs/configuration/modules/core.md#worker-connections)).
### `requests`
Суммарное число клиентских запросов.
### `Reading`
Текущее число соединений, в которых Angie в настоящий момент читает заголовок запроса.
### `Writing`
Текущее число соединений, в которых Angie в настоящий момент отвечает клиенту.
### `Waiting`
Текущее число бездействующих клиентских соединений в ожидании запроса.
## Встроенные переменные
### `$connections_active`
то же, что и значение Active connections;
### `$connections_reading`
то же, что и значение Reading;
### `$connections_writing`
то же, что и значение Writing;
### `$connections_waiting`
то же, что и значение Waiting.
# https://angie.software/angie/docs/configuration/modules/http/http_sub.md
# Sub
Фильтр, изменяющий в ответе одну заданную строку на другую.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_sub_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
## Пример конфигурации
```nginx
location / {
sub_filter '
## Директивы
### sub_filter
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `sub_filter` строка замена; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает строку, которую нужно заменить, и строку замены. Заменяемая строка проверяется без учета регистра. В заменяемой строке и в строке замены можно использовать переменные. На одном уровне конфигурации может быть указано несколько директив `sub_filter`. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы `sub_filter`.
### sub_filter_last_modified
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `sub_filter_last_modified` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `sub_filter_last_modified off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет сохранить поле заголовка `Last-Modified` исходного ответа во время замены для лучшего кэширования ответов.
По умолчанию поле заголовка удаляется, так как содержимое ответа изменяется во время обработки.
### sub_filter_once
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `sub_filter_once` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `sub_filter_once on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, сколько раз нужно искать каждую из заменяемых строк: один раз или многократно.
### sub_filter_types
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `sub_filter_types` mime-тип ...; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `sub_filter_types text/html;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает замену строк в ответах с указанными MIME-типами в дополнение к `text/html`. Специальное значение "\*" соответствует любому MIME-типу.
# https://angie.software/angie/docs/configuration/modules/http/http_upstream.md
# 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).
## Пример конфигурации
```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;
}
}
```
## Директивы
### 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 {
zone my_backend 1m;
server primary1.example.com;
server primary2.example.com;
server backup1.example.com backup;
server backup2.example.com backup;
backup_switch permanent=2m;
}
```
Если балансировщик переключается с основных серверов на резервную группу,
все последующие запросы обрабатываются этой резервной группой в течение 2 минут.
По истечении 2 минут балансировщик повторно проверяет основные серверы
и снова делает их активными, если они работают нормально.
### 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 {
zone ntlm_backend 1m;
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 "";
# ...
}
}
```
### 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` механизм балансировки нагрузки по обратной связи.
Он динамически корректирует решения при балансировке,
умножая вес каждого проксируемого сервера на среднее значение обратной связи,
которое меняется с течением времени в зависимости от значения переменной
и подчиняется необязательному условию.
Могут быть заданы следующие параметры:
| `переменная` | Переменная, из которой берется значение обратной связи.
Она должна представлять собой метрику производительности или состояния;
предполагается, что сервер передает ее в заголовках или иным образом.
Значение оценивается при каждом ответе от сервера
и учитывается в скользящем среднем
согласно настройкам `inverse` и `factor`. |
|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `inverse` | Если параметр задан, значение обратной связи интерпретируется наоборот:
более низкие значения указывают на лучшую производительность. |
| `factor` | Коэффициент, по которому значение обратной связи учитывается
при расчете среднего.
Допустимы целые числа от 0 до 99.
По умолчанию — `90`.
Среднее рассчитывается по формуле [экспоненциального сглаживания](https://ru.wikipedia.org/wiki/Экспоненциальное_сглаживание).
Чем больше коэффициент, тем меньше новые значения влияют на среднее;
если указать `90`, то будет взято 90 % от предыдущего значения
и лишь 10 % от нового. |
| `account` | Указывает условную переменную,
которая контролирует, какие ответы учитываются при расчете.
Среднее значение обновляется с учетом значения обратной связи из ответа,
только если условная переменная этого ответа
не равна `""` или `"0"`.
#### NOTE
По умолчанию ответы в ходе [активных проверок](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)
не включаются в расчет;
комбинация переменной [$upstream_probe](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe)
с `account` позволяет включить эти ответы
или даже исключить все остальное. |
| `last_byte` | Позволяет обрабатывать данные от проксируемого сервера после получения
полного ответа, а не только заголовка. |
Пример:
```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`
или ответы на обычные клиентские запросы.
### 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.
### 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 {
zone backend 1m;
ip_hash;
server backend1.example.com;
server backend2.example.com;
server backend3.example.com down;
server backend4.example.com;
}
```
### 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 {
zone memcached_backend 1m;
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 {
zone http_backend 1m;
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 {
zone fastcgi_backend 1m;
server 127.0.0.1:9000;
keepalive 8;
}
server {
#...
location /fastcgi/ {
fastcgi_pass fastcgi_backend;
fastcgi_keep_conn on;
# ...
}
}
```
#### NOTE
Протоколы SCGI и uwsgi не определяют семантику постоянных соединений.
### 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 |
Задает максимальное число запросов, которые можно сделать по одному постоянному соединению. После того как сделано максимальное число запросов, соединение закрывается.
Периодическое закрытие соединений необходимо для освобождения памяти, выделенной под конкретные соединения. Поэтому использование слишком большого максимального числа запросов может приводить к чрезмерному потреблению памяти и не рекомендуется.
### 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 |
Ограничивает максимальное время, в течение которого могут обрабатываться запросы в рамках постоянного соединения. По достижении заданного времени соединение закрывается после обработки очередного запроса.
### 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 |
Задает таймаут, в течение которого неактивное постоянное соединение с сервером группы не будет закрыто.
### 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) с учетом их весов.
### 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),
и переопределяет его, если параметр задан. |
|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `account` | Указывает условную переменную,
которая контролирует, какие ответы учитываются при расчете.
Среднее значение обновляется,
только если условная переменная ответа
не равна `""` или `"0"`.
#### NOTE
По умолчанию ответы в ходе [активных проверок](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)
не включаются в расчет;
комбинация переменной [$upstream_probe](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe)
с `account` позволяет включить эти ответы
или даже исключить все остальное. |
Текущие значения представлены как `header_time` (только заголовки)
и `response_time` (ответы целиком) в объекте `health` сервера
среди [метрик апстрима](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-upstreams) в API.
### 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` должна использоваться после всех директив,
задающих тот или иной метод балансировки нагрузки, иначе она не будет
работать.
### 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), при котором запрос передается на сервер с наименьшим количеством активных соединений.
### 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` — только если получен весь ответ.
### 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`.
`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` | Отключает учет попыток. |
`fail_timeout=`время — задает период времени, в течение которого
должно произойти определенное число неудачных попыток связи с сервером
([max_fails](#max-fails)), чтобы сервер считался недоступным.
Затем сервер остается недоступным в течение того же самого времени,
прежде чем будет проверен повторно.
Значение по умолчанию — 10 секунд.
#### NOTE
Если директива `server` в группе разрешается в несколько серверов,
ее настройка `fail_timeout` применяется к каждому серверу отдельно.
Если после разрешения всех директив `server`
в апстриме остается только один сервер,
настройка `fail_timeout` не действует и будет проигнорирована.
| `backup` | Помечает сервер как запасной. На него будут передаваться запросы в случае, если не работают основные серверы.
Если задана директива [backup_switch (PRO)](#u-backup-switch),
также применяется ее логика активного резервирования. |
|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `down` | Помечает сервер как постоянно недоступный. |
| `drain` (PRO) | Помечает сервер как разгружаемый (draining); это значит,
что он получает только запросы сессий,
привязанных ранее через [sticky](#u-sticky).
В остальном поведение такое же, как в режиме `down`. |
#### WARNING
Параметр `backup` нельзя использовать совместно с методами
балансировки нагрузки [hash](#u-hash), [ip_hash](#u-ip-hash) и
[random](#u-random).
Параметры `down` и `drain` взаимно исключающие.
| `resolve` | Позволяет отслеживать изменения списка IP-адресов, соответствующего
доменному имени, и обновлять его без перезагрузки конфигурации.
При этом группа должна находиться в
[зоне разделяемой памяти](#u-zone);
также должен быть определен
[преобразователь имен в адреса](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver). |
|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `service=`имя | Включает преобразование SRV-записей DNS и задает имя сервиса. Для
работы параметра необходимо задать параметр `resolve` у сервера,
не указывая порт сервера при имени хоста.
Если в имени службы нет точек, формируется имя по стандарту RFC:
к имени службы добавляется префикс `_`,
затем через точку добавляется `_tcp`.
Так, имя службы `http` даст в результате `_http._tcp`.
Angie разрешает SRV-записи,
объединяя нормализованное имя службы и имя хоста
и получая список серверов для полученной комбинации через DNS,
вместе с их приоритетами и весами.
- SRV-записи с наивысшим приоритетом
(те, которые имеют минимальное значение приоритета)
разрешаются как основные серверы,
а прочие записи становятся запасными серверами.
Если `backup` установлено с `server`,
SRV-записи с наивысшим приоритетом разрешаются как запасные серверы,
а прочие записи игнорируются.
- Вес аналогичен параметру `weight` директивы `server`.
Если вес задан как в самой директиве, так и в SRV-записи,
используется вес, установленный в директиве. |
В этом примере выполняется поиск записи `_http._tcp.backend.example.com`:
```nginx
server backend.example.com service=http resolve;
```
| `sid=`id | Задает ID сервера в группе. Если параметр не задан,
то ID задается как шестнадцатеричный MD5-хэш
IP-адреса и порта или пути UNIX-сокета. |
|------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| `slow_start=`время | Задает [время](https://angie.software//angie/docs/configuration/configfile.md#syntax) восстановления веса сервера,
возвращающегося к работе
при балансировке нагрузки методом
[round-robin](#round-robin) или [least_conn](#u-least-conn).
Если параметр задан
и сервер после сбоя снова считается работающим
с точки зрения [max_fails](#max-fails) и [upstream_probe (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe),
то такой сервер равномерно набирает указанный для него вес
в течение заданного времени.
Если параметр не задан,
то в аналогичной ситуации
сервер сразу начинает работу с указанным для него весом. |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### NOTE
Если в апстриме задан только один `server`,
`slow_start` не работает и будет игнорироваться.
### 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)).
### sticky
#### Versionchanged
Изменено в версии 1.10.0: PRO
#### Versionchanged
Изменено в версии 1.11.0.
#### Versionchanged
Изменено в версии 1.11.0: PRO
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `sticky` cookie name [attr=значение]...;
`sticky route` значение...;
`sticky learn` `zone=`зона `create=`$create_var1... `lookup=`$lookup_var1... [`header`] [`norefresh`] [`timeout=`время];
`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 {
zone backend 1m;
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 {
zone backend 1m;
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 {
zone backend 1m;
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`;
каждая группа должна использовать свою собственную зону.
### 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 {
zone backend 1m;
server backend1.example.com:8080;
server backend2.example.com:8080;
sticky cookie cookie_name;
sticky_secret my_secret.$remote_addr;
}
```
Соль добавляется после хэшируемого значения;
чтобы независимо проверить механизм хэширования:
```console
$ echo -n "" | md5sum
```
### 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,
если желаемый сервер недоступен,
вместо использования любого другого доступного сервера,
как это происходит, когда в группе нет доступных серверов.
### 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 {
zone backend 1m;
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;
}
```
По умолчанию запросы распределяются по серверам циклически (в режиме round-robin) с учетом весов серверов. В вышеприведенном примере каждые 7 запросов будут распределены так: 5 запросов на backend1.example.com и по одному запросу на второй и третий серверы. Распределение является *равномерным*: запросы к серверу с большим весом распределяются по всему циклу, а не отправляются подряд одной группой.
Если при попытке работы с сервером происходит ошибка, то запрос передается следующему серверу, и так далее до тех пор, пока не будут опробованы все работающие серверы. Если не удастся получить успешный ответ ни от одного из серверов, то клиенту будет возвращен результат работы с последним сервером.
#### NOTE
По умолчанию сервер, у которого изредка происходят неудачные попытки,
не достигающие порога [max_fails](#max-fails),
временно получает меньшую долю запросов
и восстанавливает свою полную долю в течение последующих запросов.
Это отличается от [slow_start](#slow-start),
который плавно возвращает сервер к работе только после того,
как сервер был помечен недоступным и затем восстановился.
### zone
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `zone` имя [размер]; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | upstream |
Задает имя и размер зоны разделяемой памяти, в которой хранятся конфигурация группы и ее рабочее состояние, разделяемые между рабочими процессами. В одной и той же зоне могут быть сразу несколько групп. В этом случае достаточно указать размер только один раз.
#### NOTE
Содержимое зоны сохраняется при перезагрузке только в том случае, если
настроенный `размер` не изменился. Любое изменение — увеличение
или уменьшение — приводит к пересозданию зоны с потерей всех данных.
#### NOTE
Метрики группы собираются, только если настроена эта зона. Без нее группа
не отображается в [/status/http/upstreams/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-upstreams),
в [виджете «HTTP Upstreams»](https://angie.software//angie/docs/configuration/monitoring.md#console-http-upstreams-widget)
и в выводе [Prometheus](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus),
и предупреждение при этом не выводится.
См. [пример конфигурации](https://angie.software//angie/docs/configuration/modules/http/http_api.md#example-configuration).
## Встроенные переменные
Модуль `http_upstream` поддерживает следующие встроенные переменные:
### `$sticky_sessid`
Используется с `remote_action` в [sticky](#u-sticky);
хранит начальный идентификатор сессии, взятый из `lookup`.
### `$sticky_sid`
Используется с `remote_action` в [sticky](#u-sticky);
хранит идентификатор сервера, предварительно связанный с сессией.
### `$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).
### `$upstream_bytes_received`
число байт, полученных от сервера группы. Значения нескольких соединений разделяются запятыми и двоеточиями подобно адресам в переменной [$upstream_addr](#v-upstream-addr).
### `$upstream_bytes_sent`
число байт, переданных на сервер группы. Значения нескольких соединений разделяются запятыми и двоеточиями подобно адресам в переменной [$upstream_addr](#v-upstream-addr).
### `$upstream_cache_status`
хранит статус доступа к кэшу ответов. Статус может быть одним из `MISS`,
`BYPASS`, `EXPIRED`, `STALE`, `UPDATING`,
`REVALIDATED` или `HIT`:
- `MISS`: Ответ не найден в кэше,
и запрос передан на сервер.
- `BYPASS`: Кэш обойден,
и запрос напрямую передан на сервер.
- `EXPIRED`: Ответ в кэше устарел,
и на сервер передан новый запрос для обновления контента.
- `STALE`: Ответ в кэше устарел,
но по-прежнему передается клиентам,
пока через какое-то время не произойдет обновление контента c сервера.
- `UPDATING`: Ответ в кэше устарел,
но по-прежнему передается клиентам,
пока уже идущее обновление контента c сервера не завершится.
- `REVALIDATED`: Ответ в кэше устарел,
но был успешно перепроверен
и не нуждается в обновлении с сервера.
- `HIT`: Ответ был взят из кэша.
Если запрос пошел в обход кэша без обращения к нему,
переменная не устанавливается.
### `$upstream_cache_key`
#### Versionadded
Добавлено в версии 1.11.0.
содержит используемый ключ кэширования.
### `$upstream_connect_time`
хранит время, затраченное на установление соединения с сервером группы; время хранится в секундах с точностью до миллисекунд. В случае SSL включает в себя время, потраченное на рукопожатие. Времена нескольких соединений разделяются запятыми и двоеточиями подобно адресам в переменной [$upstream_addr](#v-upstream-addr).
### `$upstream_cookie_<имя>`
cookie с указанным именем, переданный сервером группы в поле `Set-Cookie` заголовка ответа. Необходимо иметь в виду, что cookie запоминаются только из ответа последнего сервера.
### `$upstream_header_time`
хранит время, затраченное на получение заголовка ответа от сервера группы; время хранится в секундах с точностью до миллисекунд. Времена нескольких ответов разделяются запятыми и двоеточиями подобно адресам в переменной [$upstream_addr](#v-upstream-addr).
### `$upstream_http_<имя>`
хранят поля заголовка ответа сервера. Например, поле заголовка ответа `Server` доступно в переменной `$upstream_http_server`. Правила преобразования имен полей заголовка ответа в имена переменных такие же, как для переменных с префиксом `$http_`. Необходимо иметь в виду, что поля заголовка запоминаются только из ответа последнего сервера.
### `$upstream_request_method`
#### Versionadded
Добавлено в версии 1.11.0.
метод запроса, используемый при обращении к upstream. Он может отличаться от
метода запроса клиента, когда кэширование преобразует `HEAD` в
`GET` или задана директива [proxy_method](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-method).
### `$upstream_queue_time`
хранит время, проведенное запросом в [очереди](#u-queue)
до очередного выбора сервера
и выраженное в секундах с точностью до миллисекунд.
Времена нескольких попыток разделяются запятыми и двоеточиями
подобно адресам в переменной [$upstream_addr](#v-upstream-addr).
### `$upstream_response_length`
хранит длину ответа, полученного от сервера группы; длина хранится в байтах. Длины нескольких ответов разделяются запятыми и двоеточиями подобно адресам в переменной [$upstream_addr](#v-upstream-addr).
### `$upstream_response_time`
хранит время, затраченное на получение ответа от сервера группы; время хранится в секундах с точностью до миллисекунд. Времена нескольких ответов разделяются запятыми и двоеточиями подобно адресам в переменной [$upstream_addr](#v-upstream-addr).
### `$upstream_status`
хранит статус ответа, полученного от сервера группы. Статусы нескольких ответов разделяются запятыми и двоеточиями подобно адресам в переменной [$upstream_addr](#v-upstream-addr). Если сервер не может быть выбран, то переменная хранит статус 502 (Bad Gateway).
### `$upstream_sticky_status`
Статус привязанных запросов.
| `""` | Запрос отправлен в группу серверов, где привязка не включена. |
|--------|----------------------------------------------------------------------------------|
| `NEW` | Запрос не содержит информации о привязке к серверу. |
| `HIT` | Запрос с привязкой отправлен на желаемый сервер. |
| `MISS` | Запрос с привязкой отправлен на сервер,
выбранный по алгоритму балансировки. |
Статусы из нескольких соединений разделяются запятыми и двоеточиями
подобно адресам в переменной [$upstream_addr](#v-upstream-addr).
### `$upstream_trailer_<имя>`
хранит поля из конца ответа, полученного от сервера группы.
# https://angie.software/angie/docs/configuration/modules/http/http_upstream_probe.md
# Upstream Probe
Реализует активные проверки работоспособности (health probes)
для [Upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).
## Пример конфигурации
```nginx
server {
listen ...;
location /backend {
...
proxy_pass http://backend;
upstream_probe backend_probe
uri=/probe
port=10004
interval=5s
test=$good
essential
fails=3
passes=3
max_body=10m
mode=idle;
}
}
```
## Директивы
### upstream_probe (PRO)
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `upstream_probe` имя [`uri=`адрес] [`port=`число] [`interval=`время] [`method=`метод] [`test=`условие] [`essential` [`persistent`]] [`fails=`число] [`passes=`число] [`max_body=`размер] [`mode=``always` | `idle` | `onfail`]; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Задает активную проверку работоспособности серверов тех [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream),
которые указаны в директивах [proxy_pass](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass), [uwsgi_pass](https://angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass) и т. д.
в том же контексте `location`, где находится директива `upstream_probe`.
При этом Angie регулярно выполняет запросы согласно указанным параметрам
к каждому серверу в составе апстрима.
Сервер проходит проверку, если запрос к нему успешно выполняется с учетом всех
параметров самой директивы `upstream_probe` и всех параметров, влияющих на
использование апстримов тем контекстом `location`, где она задана. Это
касается в том числе директив [proxy_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream),
[uwsgi_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-next-upstream) и пр., а также [proxy_set_header](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-set-header) и т. д.
Чтобы использовать проверки,
в апстриме необходима зона разделяемой памяти ([zone](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone)).
Для одного апстрима можно определить несколько проверок.
Могут быть заданы следующие параметры:
| `имя` | Обязательное имя проверки. |
|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `uri` | URI запроса, который добавляется к аргументу [proxy_pass](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass),
[uwsgi_pass](https://angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass) и т. д. По умолчанию — `/`. |
| `port` | Альтернативный порт для запроса. |
| `interval` | Интервал между проверками. По умолчанию — `5s`. |
| `method` | HTTP-метод запроса проверки. По умолчанию — `GET`. |
| `test` | Проверяемое при запросе условие; задается строкой с переменными.
Если результат подстановки переменных — `""` или `"0"`,
проверка не пройдена. |
| `essential` | Если параметр задан, то изначально состояние сервера подлежит уточнению
и клиентские запросы не передаются ему, пока проверка не будет пройдена. |
| `persistent` | Установка этого параметра требует сначала включить `essential`;
серверы с `persistent`, работавшие до
[перезагрузки конфигурации](https://angie.software//angie/docs/configuration/configfile.md#configfile-reloading),
начинают получать запросы без необходимости сначала пройти эту проверку. |
| `fails` | Число последовательных неуспешных запросов,
при котором проверка считает сервер неработающим.
По умолчанию — 1. |
| `passes` | Число последовательных успешных запросов,
при котором проверка считает сервер работающим.
По умолчанию — 1. |
| `max_body` | Максимальный объем памяти для тела ответа.
По умолчанию — `256k`. |
| `mode` | Режим проверки в зависимости от работоспособности серверов:
- `always` — серверы проверяются независимо от состояния;
- `idle` — проверяются неработающие серверы, а также серверы,
где с последнего клиентского запроса прошло время `interval`.
- `onfail` — проверяются серверы только в неработающем состоянии.
По умолчанию — `always`. |
Пример:
```nginx
upstream backend {
zone backend 1m;
server backend1.example.com;
server backend2.example.com;
}
map $upstream_status $good {
200 "1";
}
server {
listen ...;
location /backend {
...
proxy_pass http://backend;
upstream_probe backend_probe
uri=/probe
port=10004
interval=5s
test=$good
essential
persistent
fails=3
passes=3
max_body=10m
mode=idle;
}
}
```
Детали работы:
- Изначально сервер не получает клиентские запросы,
пока не пройдет *все* заданные для него проверки с параметром `essential`
(пропуская помеченные как `persistent`, если конфигурация перезагружена
и до этого сервер считался работающим).
Если таких проверок нет, сервер считается работающим.
- Сервер считается неработающим и не получает клиентские запросы,
если *какая-либо* заданная для него проверка достигает своего порога `fails`
или сам сервер достигает порога [max_fails](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails).
- Чтобы неработающий сервер снова мог считаться работающим,
*все* заданные для него проверки должны достичь своего порога `passes`;
после этого учитывается порог [max_fails](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails).
## Встроенные переменные
Модуль `http_upstream_probe` поддерживает следующие встроенные переменные:
### `$upstream_probe` (PRO)
Имя активной сейчас проверки [upstream_probe](#u-upstream-probe).
### `$upstream_probe_body` (PRO)
Тело ответа от сервера,
полученного при проверке [upstream_probe](#u-upstream-probe).
Его размер ограничен параметром `max_body`.
# https://angie.software/angie/docs/configuration/modules/http/http_userid.md
# UserID
Выдает cookie для идентификации клиентов. Для записи в лог полученных и выданных cookie можно использовать встроенные переменные [$uid_got](#v-uid-got) и [$uid_set](#v-uid-set). Модуль совместим с модулем [mod_uid](http://www.lexa.ru/programs/mod-uid.html) для Apache.
## Пример конфигурации
```nginx
userid on;
userid_name uid;
userid_domain example.com;
userid_path /;
userid_expires 365d;
userid_p3p 'policyref="/w3c/p3p.xml", CP="CUR ADM OUR NOR STA NID"';
```
## Директивы
### userid
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `userid` `on` | `v1` | `log` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `userid off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает выдачу cookie и запись приходящих cookie в лог:
| `on` | разрешает выдачу cookie версии 2 и запись приходящих cookie в лог; |
|--------|-----------------------------------------------------------------------|
| `v1` | разрешает выдачу cookie версии 1 и запись приходящих cookie в лог; |
| `log` | запрещает выдачу cookie, но разрешает запись приходящих cookie в лог; |
| `off` | запрещает выдачу cookie и запись приходящих cookie в лог. |
### userid_domain
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `userid_domain` имя | `none`; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `userid_domain none;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает домен, для которого устанавливается cookie. Параметр `none` запрещает выдавать домен для cookie.
### userid_expires
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `userid_expires` время | `max` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| По умолчанию | `userid_expires off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает время, в течение которого браузер должен хранить cookie. Параметр max устанавливает срок хранения cookie до 31 декабря 2037 года 23:55:55 GMT. Указание параметра `off` позволяет ограничить время действия cookie сессией браузера.
### userid_flags
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `userid_flags` `off` | флаг ...; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `userid_flags off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если параметр не `off`, задает один или несколько дополнительных флагов для cookie: secure, httponly, samesite=strict, samesite=lax, samesite=none.
### userid_mark
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `userid_mark` буква | цифра | = | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `userid_mark off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если параметр не `off`, включает механизм маркировки cookie и задает символ, используемый в качестве метки. Этот механизм позволяет добавить или изменить [userid_p3p](#userid-p3p) и/или время хранения cookie, но при этом оставить неизменным идентификатор клиента. Меткой может быть любая буква английского алфавита (с учетом регистра), цифра или знак "=".
Если метка задана, то она сравнивается с первым дополняющим символом в base64 представлении идентификатора клиента, передаваемом в cookie. Если они не совпадают, то cookie перепосылается с заданной меткой, временем хранения и заголовком `P3P`.
### userid_name
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `userid_name` имя; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | `userid_name uid;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает имя cookie.
### userid_p3p
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `userid_p3p` строка | `none`; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `userid_p3p none;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает значение для поля заголовка `P3P`, которое будет выдаваться вместе с cookie. Если задано специальное значение `none`, то в ответе не будет заголовка `P3P`.
### userid_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `userid_path` путь; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | `userid_path /;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает путь, для которого устанавливается cookie.
### userid_service
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `userid_service` номер; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `userid_service ;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если идентификаторы выдаются несколькими серверами (сервисами), то каждому
сервису следует назначить свой собственный `номер`, для обеспечения
уникальности выдаваемых идентификаторов клиентов. По умолчанию для cookie первой
версии используется ноль. Для cookie второй версии по умолчанию используется
число, составленное из последних четырех октетов IP-адреса сервера.
## Встроенные переменные
### `$uid_got`
Имя cookie и полученный идентификатор клиента.
### `$uid_reset`
Если значением является непустая строка не равная `0`, то клиентские идентификаторы перевыдаются. Специальное значение `log` дополнительно приводит к выдаче сообщений о перевыданных идентификаторах в [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log).
### `$uid_set`
Имя cookie и выданный идентификатор клиента.
# https://angie.software/angie/docs/configuration/modules/http/http_uwsgi.md
# uWSGI
Позволяет передавать запросы uWSGI-серверу.
## Пример конфигурации
```nginx
location / {
include uwsgi_params;
uwsgi_pass localhost:9000;
}
```
## Директивы
### uwsgi_bind
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_bind` адрес [`transparent`] | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает локальный IP-адрес с необязательным портом, который будет использоваться в исходящих соединениях с uwsgi-сервером. В значении параметра допустимо использование переменных. Специальное значение `off` отменяет действие унаследованной с предыдущего уровня конфигурации директивы uwsgi_bind, позволяя системе самостоятельно выбирать локальный IP-адрес и порт.
Параметр `transparent` позволяет задать нелокальный IP-aдрес, который будет использоваться в исходящих соединениях с uwsgi-сервером, например, реальный IP-адрес клиента:
```nginx
uwsgi_bind $remote_addr transparent;
```
Для работы параметра обычно требуется запустить рабочие процессы Angie с привилегиями [суперпользователя](https://angie.software//angie/docs/configuration/modules/core.md#user). В Linux это не требуется, так как если указан параметр transparent, то рабочие процессы наследуют capability CAP_NET_RAW из главного процесса.
#### NOTE
Необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с uwsgi-сервера.
### uwsgi_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_buffer_size` размер; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `uwsgi_buffer_size 4k|8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает размер буфера, в который будет читаться первая часть ответа, получаемого от uwsgi-сервера. В этой части ответа обычно находится небольшой заголовок ответа. По умолчанию размер одного буфера равен размеру страницы памяти. В зависимости от платформы это или 4K, или 8K, однако его можно сделать меньше.
### uwsgi_buffering
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_buffering` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `uwsgi_buffering on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает использовать буферизацию ответов uwsgi-сервера.
| `on` | Angie принимает ответ uwsgi-сервера как можно быстрее, сохраняя его в
буферы, заданные директивами [uwsgi_buffer_size](#uwsgi-buffer-size) и
[uwsgi_buffers](#uwsgi-buffers). Отправка клиенту при этом выполняется
параллельно: заполненные буферы передаются на отправку (никто их не
удерживает), но суммарно не более значения
[uwsgi_busy_buffers_size](#uwsgi-busy-buffers-size). Если буфер заполнен не полностью, то на
отправку он не передается, если только это не последние данные ответа.
Поэтому для моментальной передачи каждых нескольких байт режим
буферизированного чтения не подходит. Если ответ не вмещается целиком в
память, то его часть может быть записана на диск во [временный файл](#uwsgi-temp-path). Запись во временные файлы контролируется
директивами [uwsgi_max_temp_file_size](#uwsgi-max-temp-file-size) и
[uwsgi_temp_file_write_size](#uwsgi-temp-file-write-size). |
|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | Ответ передается клиенту сразу же по мере его поступления. Angie
работает в цикле «прочитал — отправил» и не ждет, пока буфер заполнится
целиком: например, прочитанные 10 байт из буфера 4К будут сразу
отправлены клиенту. При этом если весь ответ умещается в буфер, Angie
может прочитать его целиком. Максимальный размер данных, который Angie
может принять от сервера за один раз, задается директивой
[uwsgi_buffer_size](#uwsgi-buffer-size). При `off` не работает
[uwsgi_limit_rate](#uwsgi-limit-rate). |
Буферизация может быть также включена или выключена путем передачи значения "yes" или "no" в поле `X-Accel-Buffering` заголовка ответа. Эту возможность можно запретить с помощью директивы [uwsgi_ignore_headers](#uwsgi-ignore-headers).
### uwsgi_buffers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_buffers` число размер; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `uwsgi_buffers 8 4k | 8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число и размер буферов для одного соединения, в которые будет читаться ответ, получаемый от uwsgi-сервера.
По умолчанию размер одного буфера равен размеру страницы. В зависимости от платформы это или 4K, или 8K.
### uwsgi_busy_buffers_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_busy_buffers_size` размер; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `uwsgi_busy_buffers_size 8k | 16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
При включенной [буферизации](#uwsgi-buffering) ответов uwsgi-сервера директива ограничивает суммарный размер буферов, которые могут быть заняты для отправки ответа клиенту, пока ответ еще не прочитан целиком. Оставшиеся буферы тем временем могут использоваться для чтения ответа и, при необходимости, буферизации части ответа во временный файл.
По умолчанию размер ограничен величиной двух буферов, заданных директивами [uwsgi_buffer_size](#uwsgi-buffer-size) и [uwsgi_buffers](#uwsgi-buffers).
### uwsgi_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_cache` зона | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `uwsgi_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает зону разделяемой памяти, используемой для кэширования. Одна и та же зона может использоваться в нескольких местах. В значении параметра можно использовать переменные.
| `off` | запрещает кэширование, унаследованное с предыдущего уровня конфигурации. |
|---------|----------------------------------------------------------------------------|
### uwsgi_cache_background_update
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_cache_background_update` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| По умолчанию | `uwsgi_cache_background_update off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запустить фоновый подзапрос для обновления просроченного элемента кэша, в то время как клиенту возвращается устаревший кэшированный ответ.
#### WARNING
Использование устаревшего кэшированного ответа в момент его обновления должно быть [разрешено](#uwsgi-cache-use-stale-updating).
### uwsgi_cache_bypass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_cache_bypass` ...; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает условия, при которых ответ не будет браться из кэша. Если значение хотя бы одного из строковых параметров непустое и не равно "0", то ответ не берется из кэша:
```nginx
uwsgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
uwsgi_cache_bypass $http_pragma $http_authorization;
```
Можно использовать совместно с директивой [uwsgi_no_cache](#uwsgi-no-cache).
### uwsgi_cache_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_cache_key` строка; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает ключ для кэширования, например,
```nginx
uwsgi_cache_key localhost:9000$request_uri;
```
### uwsgi_cache_lock
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_cache_lock` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `uwsgi_cache_lock off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если включено, одновременно только одному запросу будет позволено заполнить новый элемент кэша, идентифицируемый согласно директиве [uwsgi_cache_key](#uwsgi-cache-key), передав запрос на uwsgi-сервер. Остальные запросы этого же элемента будут либо ожидать появления ответа в кэше, либо освобождения блокировки этого элемента, в течение времени, заданного директивой [uwsgi_cache_lock_timeout](#uwsgi-cache-lock-timeout).
### uwsgi_cache_lock_age
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_cache_lock_age` время; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `uwsgi_cache_lock_age 5s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если последний запрос, переданный на uwsgi-сервер для заполнения нового элемента кэша, не завершился за указанное время, на uwsgi-сервер может быть передан еще один запрос.
### uwsgi_cache_lock_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_cache_lock_timeout` время; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `uwsgi_cache_lock_timeout 5s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут для [uwsgi_cache_lock](#uwsgi-cache-lock). По истечении указанного времени запрос будет передан на uwsgi-сервер, однако ответ не будет кэширован.
### uwsgi_cache_max_range_offset
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_cache_max_range_offset` число; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает смещение в байтах для запросов с указанием диапазона запрашиваемых байт (byte-range requests). Если диапазон находится за указанным смещением, range-запрос будет передан на uwsgi-сервер и ответ не будет кэширован.
### uwsgi_cache_methods
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_cache_methods` `GET` | `HEAD` | `POST` ...; |
|------------------------------------------------------------------------------------------|------------------------------------------------------|
| По умолчанию | `uwsgi_cache_methods GET HEAD;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если метод запроса клиента указан в этой директиве, то ответ будет кэширован. Методы "GET" и "HEAD" всегда добавляются в список, но тем не менее рекомендуется перечислять их явно. См. также директиву [uwsgi_no_cache](#uwsgi-no-cache).
### uwsgi_cache_min_uses
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_cache_min_uses` число; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `uwsgi_cache_min_uses 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число запросов, после которого ответ будет кэширован.
#### WARNING
Метаданные кэша хранятся в разделяемой памяти. Ручное удаление файлов кэша не
сбрасывает счетчики и может привести к непредсказуемому поведению. Для
полного сброса остановите сервер, удалите директорию кэша и запустите снова.
#### NOTE
Сторонние модули очистки кэша (например, [Cache Purge](https://angie.software//angie/docs/installation/external-modules/cache-purge.md#external-cache-purge)) удаляют только
файлы, но не сбрасывают счетчик uwsgi_cache_min_uses. Директива
предназначена для защиты кэша от загрязнения редкими запросами, и сброс
счетчика при очистке может негативно повлиять на производительность.
### uwsgi_cache_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_cache_path` путь [`levels=`уровни] [`use_temp_path=``on` | `off`] `keys_zone=`имя:размер [`inactive=`время] [`max_size=`размер] [`min_free=`размер] [`manager_files=`число] [`manager_sleep=`время] [`manager_threshold=`время] [`loader_files=`число] [`loader_sleep=`время] [`loader_threshold=`время]; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает путь и другие параметры кэша. Данные кэша хранятся в файлах. Именем файла в кэше является результат функции MD5 от [ключа кэширования](#uwsgi-cache-key).
Параметр `levels` задает уровни иерархии кэша: можно задать от 1 до 3 уровней, на каждом уровне допускаются значения 1 или 2.
Например, при использовании
```nginx
uwsgi_cache_path /data/angie/cache levels=1:2 keys_zone=one:10m;
```
имена файлов в кэше будут такого вида:
```nginx
/data/angie/cache/c/29/b7f54b2df7773722d382f4809d65029c
```
Кэшируемый ответ сначала записывается во временный файл, а потом этот файл переименовывается. Временные файлы и кэш могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешевой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если кэш будет находиться на той же файловой системе, что и каталог с временными файлами.
Какой из каталогов будет использоваться для временных файлов, определяется параметром `use_temp_path`.
| `on` | Если параметр не задан или установлен в значение "on", будет использоваться каталог, задаваемый директивой [uwsgi_temp_path](#uwsgi-temp-path) для данного location |
|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | временные файлы будут располагаться непосредственно в каталоге кэша |
Кроме того, все активные ключи и информация о данных хранятся в зоне разделяемой памяти, имя и размер которой задаются параметром `keys_zone`. Зоны размером в 1 мегабайт достаточно для хранения около 8 тысяч ключей. Метаданные кэша хранятся в разделяемой памяти.
Если к данным кэша не обращаются в течение времени, заданного параметром `inactive`, то данные удаляются, независимо от их свежести.
По умолчанию `inactive` равен 10 минутам.
Специальный процесс **менеджера кэша** следит за максимальным размером кэша, а также за минимальным объемом свободного места на файловой системе с кэшем, и удаляет наименее востребованные данные при превышении максимального размера кэша или недостаточном объеме свободного места. Удаление данных происходит итерациями.
| `max_size` | максимальное пороговое значение размера кэша |
|---------------------|--------------------------------------------------------------------------------------------------------|
| `min_free` | минимальное пороговое значение объема свободного места на файловой системе с кэшем |
| `manager_files` | максимальное количество удаляемых элементов кэша за одну итерацию
По умолчанию: `100` |
| `manager_threshold` | ограничивает время работы одной итерации
По умолчанию: `200` миллисекунд |
| `manager_sleep` | время, в течение которого выдерживается пауза между итерациями
По умолчанию: `50` миллисекунд |
Через минуту после старта Angie активируется специальный процесс **загрузчика кэша**, который загружает в зону кэша информацию о ранее кэшированных данных, хранящихся на файловой системе. Загрузка также происходит итерациями.
| `loader_files` | максимальное количество элементов кэша к загрузке в одну итерацию
По умолчанию: `100` |
|--------------------|--------------------------------------------------------------------------------------------------------|
| `loader_threshold` | ограничивает время работы одной итерации
По умолчанию: `200` миллисекунд |
| `loader_sleep` | время, в течение которого выдерживается пауза между итерациями
По умолчанию: `50` миллисекунд |
### uwsgi_cache_revalidate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_cache_revalidate` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `uwsgi_cache_revalidate off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает ревалидацию просроченных элементов кэша при помощи условных запросов с полями заголовка `If-Modified-Since` и `If-None-Match` .
### uwsgi_cache_use_stale
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_cache_use_stale` `error` | `timeout` | `invalid_header` | `updating` | `http_500` | `http_503` | `http_403` | `http_404` | `http_429` | `off` ...; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `uwsgi_cache_use_stale off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, в каких случаях можно использовать устаревший кэшированный ответ. Параметры директивы совпадают с параметрами директивы [uwsgi_next_upstream](#uwsgi-next-upstream).
| `error` | Позволяет использовать устаревший кэшированный ответ при невозможности выбора uwsgi-сервера для обработки запроса. |
|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `updating` | Дополнительный параметр, разрешает использовать устаревший кэшированный ответ, если на данный момент он уже обновляется. Это позволяет минимизировать число обращений к uwsgi-серверам при обновлении кэшированных данных. |
Использование устаревшего кэшированного ответа может также быть разрешено непосредственно в заголовке ответа на определенное количество секунд после того, как ответ устарел:
* Расширение [stale-while-revalidate](https://datatracker.ietf.org/doc/html/rfc5861#section-3) поля заголовка `Cache-Control` разрешает использовать устаревший кэшированный ответ, если на данный момент он уже обновляется.
* Расширение [stale-if-error](https://datatracker.ietf.org/doc/html/rfc5861#section-4) поля заголовка `Cache-Control` разрешает использовать устаревший кэшированный ответ в случае ошибки.
#### NOTE
Такой способ менее приоритетен, чем задание параметров директивы.
Чтобы минимизировать число обращений к uwsgi-серверам при заполнении нового элемента кэша, можно воспользоваться директивой [uwsgi_cache_lock](#uwsgi-cache-lock).
### uwsgi_cache_valid
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_cache_valid` [код ...] время; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает время кэширования для разных кодов ответа. Например, директивы
```nginx
uwsgi_cache_valid 200 302 10m;
uwsgi_cache_valid 404 1m;
```
задают время кэширования 10 минут для ответов с кодами 200 и 302 и 1 минуту для ответов с кодом 404.
Если указано только время кэширования,
```nginx
uwsgi_cache_valid 5m;
```
то кэшируются только ответы 200, 301 и 302.
Кроме того, можно кэшировать любые ответы с помощью параметра `any`:
```nginx
uwsgi_cache_valid 200 302 10m;
uwsgi_cache_valid 301 1h;
uwsgi_cache_valid any 1m;
```
#### NOTE
Параметры кэширования могут также быть заданы непосредственно в заголовке ответа. Такой способ приоритетнее, чем задание времени кэширования с помощью директивы.
* Поле заголовка `X-Accel-Expires` задает время кэширования ответа в секундах. Значение 0 запрещает кэшировать ответ. Если значение начинается с префикса @, оно задает абсолютное время в секундах с начала эпохи, до которого ответ может быть кэширован.
* Если в заголовке нет поля `X-Accel-Expires`, параметры кэширования определяются по полям заголовка `Expires` или `Cache-Control`.
* Ответ, в заголовке которого есть поле `Set-Cookie`, не будет кэшироваться.
* Ответ, в заголовке которого есть поле `Vary` со специальным значением "\*", не будет кэшироваться. Ответ, в заголовке которого есть поле `Vary` с другим значением, будет кэширован с учетом соответствующих полей заголовка запроса.
Обработка одного или более из этих полей заголовка может быть отключена при помощи директивы [uwsgi_ignore_headers](#uwsgi-ignore-headers).
### uwsgi_connect_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_connect_timeout` время; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `uwsgi_connect_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут для установления соединения с uwsgi-сервером. Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.
### uwsgi_connection_drop
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_connection_drop` время | `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| По умолчанию | `uwsgi_connection_drop off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Настраивает завершение всех соединений с проксируемым сервером,
если он был удален из группы или помечен как постоянно недоступный
в результате процесса [reresolve](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve)
или [команды API](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods) `DELETE`.
Соединение завершается, когда обрабатывается следующее событие чтения или записи
для клиента или проксируемого сервера.
Установка времени включает [таймаут](https://angie.software//angie/docs/configuration/configfile.md#syntax) до завершения соединения;
при выборе значения `on` соединения завершаются немедленно.
### uwsgi_force_ranges
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_force_ranges` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `uwsgi_force_ranges off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Включает поддержку диапазонов запрашиваемых байт (byte-range) для кэшированных и некэшированных ответов uwsgi-сервера вне зависимости от наличия поля `Accept-Ranges` в заголовках этих ответов.
### uwsgi_hide_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_hide_header` поле; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
По умолчанию Angie не передает клиенту поля заголовка `Date`, `Server`, `X-Pad` и `X-Accel-...` из ответа uwsgi-сервера. Директива uwsgi_hide_header задает дополнительные поля, которые не будут передаваться. Если же передачу полей нужно разрешить, можно воспользоваться директивой [uwsgi_pass_header](#uwsgi-pass-header).
### uwsgi_ignore_client_abort
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_ignore_client_abort` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | `uwsgi_ignore_client_abort off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, закрывать ли соединение с uwsgi-сервером в случае, если клиент закрыл соединение, не дождавшись ответа.
### uwsgi_ignore_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_ignore_headers` поле ...; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Запрещает обработку некоторых полей заголовка из ответа uwsgi-сервера. В директиве можно указать поля `X-Accel-Redirect`, `X-Accel-Expires`, `X-Accel-Limit-Rate`, `X-Accel-Buffering`, `X-Accel-Charset`, `Expires`, `Cache-Control`, `Set-Cookie` и `Vary`.
Если не запрещено, обработка этих полей заголовка заключается в следующем:
* `X-Accel-Expires`, `Expires`, `Cache-Control`, `Set-Cookie` и `Vary` задают [параметры кэширования](#uwsgi-cache-valid) ответа;
* `X-Accel-Redirect` производит [внутреннее перенаправление](https://angie.software//angie/docs/configuration/modules/http/index.md#internal) на указанный URI;
* `X-Accel-Limit-Rate` задает [ограничение скорости](https://angie.software//angie/docs/configuration/modules/http/index.md#limit-rate) передачи ответа клиенту;
* `X-Accel-Buffering` включает или выключает [буферизацию](#uwsgi-buffering) ответа;
* `X-Accel-Charset` задает желаемую [кодировку](https://angie.software//angie/docs/configuration/modules/http/http_charset.md#id3) ответа.
### uwsgi_intercept_errors
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_intercept_errors` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `uwsgi_intercept_errors off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, передавать ли клиенту ответы uwsgi-сервера с кодом больше либо равным 300, или же перехватывать их и перенаправлять на обработку Angie с помощью директивы [error_page](https://angie.software//angie/docs/configuration/modules/http/index.md#error-page).
### uwsgi_limit_rate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_limit_rate` скорость; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `uwsgi_limit_rate 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает скорость чтения ответа от uwsgi-сервера.
Скорость задается в байтах в секунду; можно использовать переменные.
| `0` | отключает ограничение скорости |
|-------|----------------------------------|
#### NOTE
Ограничение устанавливается на запрос, поэтому, если Angie одновременно откроет два соединения к uwsgi-серверу, суммарная скорость будет вдвое выше заданного ограничения. Ограничение работает только в случае, если включена [буферизация](#uwsgi-buffering) ответов uwsgi-сервера.
### uwsgi_max_temp_file_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_max_temp_file_size` размер; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `uwsgi_max_temp_file_size 1024m;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если включена [буферизация](#uwsgi-buffering) ответов uwsgi-сервера, и ответ не вмещается целиком в буферы, заданные директивами [uwsgi_buffer_size](#uwsgi-buffer-size) и [uwsgi_buffers](#uwsgi-buffers), часть ответа может быть записана во временный файл. Эта директива задает максимальный размер временного файла. Размер данных, сбрасываемых во временный файл за один раз, задается директивой [uwsgi_temp_file_write_size](#uwsgi-temp-file-write-size).
| `0` | отключает возможность буферизации ответов во временные файлы |
|-------|----------------------------------------------------------------|
#### NOTE
Данное ограничение не распространяется на ответы, которые будут [кэшированы](#uwsgi-cache) или сохранены [на диске](#uwsgi-store).
### uwsgi_modifier1
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_modifier1` число; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `uwsgi_modifier1 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает значение поля modifier1 в заголовке пакета uwsgi.
### uwsgi_modifier2
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_modifier2` число; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `uwsgi_modifier2 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает значение поля modifier2 в заголовке пакета uwsgi.
### uwsgi_next_upstream
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_next_upstream` `error` | `timeout` | `invalid_header` | `http_500` | `http_503` | `http_403` | `http_404` | `http_429` | `non_idempotent` | `off` ...; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `uwsgi_next_upstream error timeout;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, в каких случаях запрос будет передан следующему в группе [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) серверу:
| `error` | произошла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `timeout` | произошел таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
| `invalid_header` | сервер вернул пустой или неверный ответ; |
| `http_500` | сервер вернул ответ с кодом 500; |
| `http_503` | сервер вернул ответ с кодом 503; |
| `http_403` | сервер вернул ответ с кодом 403; |
| `http_404` | сервер вернул ответ с кодом 404; |
| `http_429` | сервер вернул ответ с кодом 429; |
| `non_idempotent` | обычно запросы с [неидемпотентным](https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2) методом (POST, LOCK, PATCH) не передаются на другой сервер, если запрос серверу группы уже был отправлен; включение параметра явно разрешает повторять подобные запросы; |
| `off` | запрещает передачу запроса следующему серверу. |
#### NOTE
Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту еще ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа клиенту, то действие директивы на такой запрос не распространяется.
Директива также определяет, что считается [неудачной попыткой](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) работы с сервером.
| `error`
`timeout`
`invalid_header` | всегда считаются неудачными попытками, даже если они не указаны в директиве |
|--------------------------------------------------------|-------------------------------------------------------------------------------|
| `http_500`
`http_503`
`http_429` | считаются неудачными попытками, только если они указаны в директиве |
| `http_403`
`http_404` | никогда не считаются неудачными попытками |
Передача запроса следующему серверу может быть ограничена по [количеству попыток](#uwsgi-next-upstream-tries) и по [времени](#uwsgi-next-upstream-timeout).
### uwsgi_next_upstream_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_next_upstream_timeout` время; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `uwsgi_next_upstream_timeout 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает время, в течение которого возможна передача запроса [следующему](#uwsgi-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### uwsgi_next_upstream_tries
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_next_upstream_tries` число; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `uwsgi_next_upstream_tries 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает число допустимых попыток для передачи запроса [следующему](#uwsgi-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### uwsgi_no_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_no_cache` строка ...; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает условия, при которых ответ не будет сохраняться в кэш. Если значение хотя бы одного из строковых параметров непустое и не равно "0", то ответ не будет сохранен:
```nginx
uwsgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
uwsgi_no_cache $http_pragma $http_authorization;
```
Можно использовать совместно с директивой [uwsgi_cache_bypass](#uwsgi-cache-bypass).
### uwsgi_param
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_param` параметр значение [`if_not_empty`]; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------|
| Значение по умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Устанавливает параметр, который будет передан серверу uwsgi. Значение может
содержать текст, переменные или их комбинацию. Эти директивы наследуются с
предыдущего уровня конфигурации только в том случае, если на текущем уровне
директивы `uwsgi_param` отсутствуют.
Стандартные [переменные окружения CGI](https://datatracker.ietf.org/doc/html/rfc3875#section-4.1) следует передавать
в виде заголовков uwsgi, как показано в файле `uwsgi_params`, поставляемом
вместе с дистрибутивом:
```nginx
location / {
include uwsgi_params;
# ...
}
```
В стандартном файле `uwsgi_params` параметр `REQUEST_METHOD`
задается как `$upstream_request_method`.
Если директива указана с параметром `if_not_empty`, такой параметр будет
передан серверу только в случае, если его значение не является пустым:
```nginx
uwsgi_param HTTPS $https if_not_empty;
```
### uwsgi_pass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_pass` [протокол://] адрес; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location, if в location |
Задает протокол и адрес uwsgi-сервера. В качестве протокола можно указать `uwsgi` или `suwsgi` (secured uwsgi, uwsgi через SSL). Адрес может быть указан в виде доменного имени или IP-адреса, и порта:
```nginx
uwsgi_pass localhost:9000;
uwsgi_pass uwsgi://localhost:9000;
uwsgi_pass suwsgi://[2001:db8::1]:9090;
```
или в виде пути UNIX-сокета, который указывается после слова `unix` и заключается в двоеточия:
```nginx
uwsgi_pass unix:/tmp/uwsgi.socket;
```
Если доменному имени соответствует несколько адресов, то все они будут использоваться по очереди (round-robin). Кроме того, в качестве адреса можно указать [группу серверов](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).
В значении параметра можно использовать переменные. В этом случае, если адрес указан в виде доменного имени, имя ищется среди описанных групп серверов и если не найдено, то определяется с помощью [resolver](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver)'а.
#### NOTE
Если `uwsgi_pass` стоит в `location` с косой чертой в конце префикса
(например, `location /name/`),
и при этом в директиве [auto_redirect](https://angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) указано `default`,
запросы без косой черты в конце будут перенаправляться (`/name -> /name/`).
### uwsgi_pass_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_pass_header` поле ...; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает передавать от uwsgi-сервера клиенту [запрещенные для передачи](#uwsgi-hide-header) поля заголовка.
### uwsgi_pass_request_body
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_pass_request_body` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| По умолчанию | `uwsgi_pass_request_body on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запретить передачу исходного тела запроса на uwsgi-сервер. См. также директиву [uwsgi_pass_request_headers](#uwsgi-pass-request-headers).
### uwsgi_pass_request_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_pass_request_headers` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | `uwsgi_pass_request_headers on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запретить передачу полей заголовка исходного запроса на uwsgi-сервер. См. также директиву [uwsgi_pass_request_body](#uwsgi-pass-request-body).
### uwsgi_read_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_read_timeout` время; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `uwsgi_read_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при чтении ответа uwsgi-сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени uwsgi-сервер ничего не передаст, соединение закрывается.
### uwsgi_request_buffering
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_request_buffering` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| По умолчанию | `uwsgi_request_buffering on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает использовать буферизацию тела запроса клиента.
| `on` | тело запроса полностью [читается](https://angie.software//angie/docs/configuration/modules/http/index.md#client-body-buffer-size) от клиента перед отправкой запроса на uwsgi-сервер. |
|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | тело запроса отправляется на uwsgi-сервер сразу же по мере его поступления. В этом случае запрос не может быть передан [следующему серверу](#uwsgi-next-upstream), если Angie уже начал отправку тела запроса. |
Если для отправки тела исходного запроса используется HTTP/1.1 и передача данных частями (chunked transfer encoding), то тело запроса буферизуется независимо от значения директивы.
### uwsgi_send_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_send_timeout` время; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `uwsgi_send_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при передаче запроса uwsgi-серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени uwsgi-сервер не примет новых данных, соединение закрывается.
### uwsgi_socket_keepalive
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_socket_keepalive` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `uwsgi_socket_keepalive off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Конфигурирует поведение "TCP keepalive" для исходящих соединений к uwsgi-серверу.
| `""` | По умолчанию для сокета действуют настройки операционной системы. |
|--------|---------------------------------------------------------------------|
| `on` | для сокета включается параметр SO_KEEPALIVE |
### uwsgi_ssl_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_ssl_certificate` файл; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с сертификатом в формате PEM для аутентификации на suwsgi-сервере. В имени файла можно использовать переменные.
### uwsgi_ssl_certificate_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_ssl_certificate_cache` `off`;
`uwsgi_ssl_certificate_cache` `max=`N [`inactive=`time] [`valid=`time]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| Значение по умолчанию | `uwsgi_ssl_certificate_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет кэш для хранения [SSL-сертификатов](#uwsgi-ssl-certificate) и [секретных ключей](#uwsgi-ssl-certificate-key), заданных через переменные.
Директива поддерживает следующие параметры:
- `max` — устанавливает максимальное количество элементов в кэше. При переполнении кэша
удаляются наименее недавно использованные (LRU) элементы.
- `inactive` — определяет время, после которого элемент будет удален, если
к нему не было обращений. Значение по умолчанию — 10 секунд.
- `valid` — определяет время, в течение которого элемент кэша считается
действительным и может использоваться повторно. Значение по умолчанию — 60 секунд. По истечении этого времени
сертификаты перезагружаются или проходят повторную проверку.
- `off` — отключает кэш.
Пример:
```nginx
uwsgi_ssl_certificate $uwsgi_ssl_server_name.crt;
uwsgi_ssl_certificate_key $uwsgi_ssl_server_name.key;
uwsgi_ssl_certificate_cache max=1000 inactive=20s valid=1m;
```
### uwsgi_ssl_certificate_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_ssl_certificate_key` файл; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с секретным ключом в формате PEM для аутентификации на suwsgi-сервере.
Вместо файла можно указать значение "engine:имя:id", которое загружает ключ с указанным id из OpenSSL engine с заданным именем.
Вместо файла можно указать значение "store:scheme:id", которое используется для загрузки ключа с указанным id и URI-схемой scheme, зарегистрированной в OpenSSL provider, например [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).
В имени файла можно использовать переменные.
### uwsgi_ssl_ciphers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_ssl_ciphers` шифры; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `uwsgi_ssl_ciphers DEFAULT;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Описывает разрешенные шифры для запросов к suwsgi-серверу. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL.
Список шифров зависит от установленной версии OpenSSL.
Полный список можно посмотреть с помощью команды `openssl ciphers`.
#### WARNING
Директива `uwsgi_ssl_ciphers` *не* настраивает шифры для TLS 1.3 при
использовании OpenSSL. Для настройки шифров TLS 1.3 в OpenSSL используйте
директиву [uwsgi_ssl_conf_command](#uwsgi-ssl-conf-command), добавленную для расширенной
конфигурации SSL.
- В LibreSSL шифры TLS 1.3 *можно* настраивать с помощью
`uwsgi_ssl_ciphers`.
- В BoringSSL шифры TLS 1.3 настроить невозможно.
### uwsgi_ssl_conf_command
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_ssl_conf_command` имя значение; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает произвольные конфигурационные [команды](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) OpenSSL при установлении соединения с uwsgi HTTPS-сервером.
#### NOTE
Директива поддерживается при использовании OpenSSL 1.0.2 и выше.
Чтобы настроить шифры TLS 1.3 в OpenSSL, используйте команду `ciphersuites`.
На одном уровне может быть указано несколько директив uwsgi_ssl_conf_command. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы uwsgi_ssl_conf_command.
#### WARNING
Следует учитывать, что изменение настроек OpenSSL напрямую может привести к неожиданному поведению.
### uwsgi_ssl_crl
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_ssl_crl` файл; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Указывает файл с отозванными сертификатами (CRL) в формате PEM, используемыми при [проверке](#uwsgi-ssl-verify) сертификата suwsgi-сервера.
### uwsgi_ssl_name
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_ssl_name` имя; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | `uwsgi_ssl_name `имя хоста` из uwsgi_pass;\` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет переопределить имя сервера, используемое при [проверке](#uwsgi-ssl-verify) сертификата uwsgi HTTPS-сервера, а также для [передачи его через SNI](#uwsgi-ssl-server-name) при установлении соединения с suwsgi-сервером.
По умолчанию используется имя хоста из URL'а, заданного директивой [uwsgi_pass](#uwsgi-pass).
### uwsgi_ssl_password_file
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_ssl_password_file` файл; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с паролями от [секретных ключей](#uwsgi-ssl-certificate-key), где каждый пароль указан на отдельной строке. Пароли применяются по очереди в момент загрузки ключа.
### uwsgi_ssl_protocols
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`]; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| По умолчанию | `uwsgi_ssl_protocols TLSv1.2 TLSv1.3;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает указанные протоколы для запросов к suwsgi-серверу.
### uwsgi_ssl_server_name
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_ssl_server_name` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `uwsgi_ssl_server_name off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает передачу имени сервера,
заданного директивой [uwsgi_ssl_name](#uwsgi-ssl-name),
через расширение
[Server Name Indication](http://en.wikipedia.org/wiki/Server_Name_Indication)
протокола TLS
(SNI,
[RFC 6066](https://datatracker.ietf.org/doc/html/rfc6066.html))
при установлении соединения с защищенным uwsgi-сервером.
### uwsgi_ssl_session_reuse
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_ssl_session_reuse` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| По умолчанию | `uwsgi_ssl_session_reuse on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, использовать ли повторно SSL-сессии при работе с suwsgi-сервером. Если в логах появляются ошибки "SSL3_GET_FINISHED:digest check failed", то можно попробовать выключить повторное использование сессий.
### uwsgi_ssl_trusted_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_ssl_trusted_certificate` файл; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с доверенными сертификатами CA в формате PEM, используемыми при [проверке](#uwsgi-ssl-verify) сертификата uwsgi HTTPS-сервера.
### uwsgi_ssl_verify
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_ssl_verify` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `uwsgi_ssl_verify off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает проверку сертификата suwsgi-сервера.
### uwsgi_ssl_verify_depth
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_ssl_verify_depth` число; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `uwsgi_ssl_verify_depth 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Устанавливает глубину проверки в цепочке сертификатов suwsgi-сервера.
### uwsgi_store
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_store` `on` | `off` | строка; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `uwsgi_store off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает сохранение на диск файлов.
| `on` | сохраняет файлы в соответствии с путями, указанными в директивах [alias](https://angie.software//angie/docs/configuration/modules/http/index.md#alias) или [root](https://angie.software//angie/docs/configuration/modules/http/index.md#root) |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | запрещает сохранение файлов |
Имя файла можно задать явно с помощью `строки` с переменными:
```nginx
uwsgi_store /data/www$original_uri;
```
Время изменения файлов выставляется согласно полученному полю `Last-Modified` в заголовке ответа. Ответ сначала записывается во временный файл, а потом этот файл переименовывается. Временный файл и постоянное место хранения ответа могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешевой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой системе, что и каталог с временными файлами, задаваемый директивой [uwsgi_temp_path](#uwsgi-temp-path) для данного location.
Директиву можно использовать для создания локальных копий статических неизменяемых файлов:
```nginx
location /images/ {
root /data/www;
error_page 404 = /fetch$uri;
}
location /fetch/ {
internal;
uwsgi_pass backend:9000;
...
uwsgi_store on;
uwsgi_store_access user:rw group:rw all:r;
uwsgi_temp_path /data/temp;
alias /data/www/;
}
```
### uwsgi_store_access
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_store_access` пользователи:права ...; |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| По умолчанию | `uwsgi_store_access user:rw;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает права доступа для создаваемых файлов и каталогов, например,
```nginx
uwsgi_store_access user:rw group:rw all:r;
```
Если заданы какие-либо права для group или all, то права для user указывать необязательно:
```nginx
uwsgi_store_access group:rw all:r;
```
### uwsgi_temp_file_write_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_temp_file_write_size` размер; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `uwsgi_temp_file_write_size 8k|16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает размер данных, сбрасываемых во временный файл за один раз, при включенной буферизации ответов uwsgi-сервера во временные файлы. По умолчанию размер ограничен двумя буферами, заданными директивами [uwsgi_buffer_size](#uwsgi-buffer-size) и [uwsgi_buffers](#uwsgi-buffers). Максимальный размер временного файла задается директивой [uwsgi_max_temp_file_size](#uwsgi-max-temp-file-size).
### uwsgi_temp_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uwsgi_temp_path` путь [уровень1 [уровень2 [уровень3]]]\`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `uwsgi_temp_path uwsgi_temp;`
(путь зависит от [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-uwsgi-temp-path`) |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает имя каталога для хранения временных файлов с данными, полученными от uwsgi-серверов. В каталоге может использоваться иерархия подкаталогов до трех уровней. Например, при такой конфигурации
```nginx
uwsgi_temp_path /spool/angie/uwsgi_temp 1 2;
```
временный файл будет следующего вида:
```nginx
/spool/angie/uwsgi_temp/7/45/00000123457
```
См. также параметр use_temp_path директивы [uwsgi_cache_path](#uwsgi-cache-path).
# https://angie.software/angie/docs/configuration/modules/http/http_v2.md
# HTTP/2
Обеспечивает поддержку [HTTP/2](https://datatracker.ietf.org/doc/html/rfc9113).
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_v2_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
## Пример конфигурации
```nginx
server {
listen 443 ssl;
http2 on;
ssl_certificate server.crt;
ssl_certificate_key server.key;
}
```
#### NOTE
Чтобы принимать HTTP/2-соединения по TLS, необходимо наличие поддержки расширения "Application-Layer Protocol Negotiation" (ALPN) протокола TLS, появившейся в [OpenSSL](http://www.openssl.org/) версии 1.0.2.
Если директива [ssl_prefer_server_ciphers](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-prefer-server-ciphers) установлена в значение "on", [шифры](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ciphers) должны быть настроены таким образом, чтобы соответствовать черному списку [RFC 9113, Appendix A](https://datatracker.ietf.org/doc/html/rfc9113#appendix-A) а также поддерживаться клиентами.
## Директивы
### http2
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `http2` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | `http2 off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает протокол [HTTP/2](https://datatracker.ietf.org/doc/html/rfc9113).
### http2_body_preread_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `http2_body_preread_size` размер; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает размер буфера для каждого запроса, в который может сохраняться тело запроса до того, как оно начнет обрабатываться.
### http2_chunk_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `http2_chunk_size` размер; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `http2_chunk_size 8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает максимальный размер частей, на которое будет разделяться тело ответа. Слишком маленькое значение может привести к росту накладных расходов. Слишком большое значение может негативно сказаться на приоритизации из-за [блокировки очереди](http://en.wikipedia.org/wiki/Head-of-line_blocking).
### http2_max_concurrent_pushes
#### Deprecated
Устарело, начиная с версии 1.2.0.
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `http2_max_concurrent_pushes` число; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `http2_max_concurrent_pushes 10;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Ограничивает максимальное число параллельных [push](#http2-push)-запросов в соединении.
### http2_max_concurrent_streams
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `http2_max_concurrent_streams` число; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `http2_max_concurrent_streams 128;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает максимальное число параллельных HTTP/2-потоков в соединении.
### http2_push
#### Deprecated
Устарело, начиная с версии 1.2.0.
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `http2_push` uri | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `http2_push off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Заблаговременно отправляет ([push](https://datatracker.ietf.org/doc/html/rfc9113#name-server-push)) запрос к заданному uri вместе с ответом на оригинальный запрос. Будут обработаны только относительные URI с абсолютными путями, например:
```nginx
http2_push /static/css/main.css;
```
В значении `uri` допустимо использование переменных.
На одном уровне конфигурации можно указать несколько http2_push директив. Параметр `off` отменяет действие унаследованных с предыдущего уровня конфигурации директив http2_push.
### http2_push_preload
#### Deprecated
Устарело, начиная с версии 1.2.0.
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `http2_push_preload` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `http2_push_preload off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает автоматическое преобразование [preload links](https://www.w3.org/TR/preload/#server-push-http-2), указанных в полях "Link" заголовка ответа, в [push](https://datatracker.ietf.org/doc/html/rfc9113#name-server-push)-запросы.
### http2_recv_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `http2_recv_buffer_size` размер; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `http2_recv_buffer_size 256k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает размер входного буфера для [рабочего процесса](https://angie.software//angie/docs/configuration/modules/core.md#worker-processes).
## Встроенные переменные
Модуль http_v2 поддерживает следующие встроенные переменные:
### `$http2`
согласованный идентификатор протокола:
| `h2` | для HTTP/2 через TLS |
|--------|--------------------------------------|
| `h2c` | для HTTP/2 через незашифрованный TCP |
| `""` | пустая строка для остальных случаев |
# https://angie.software/angie/docs/configuration/modules/http/http_v3.md
# HTTP/3
Обеспечивает поддержку протокола
[HTTP/3](https://datatracker.ietf.org/doc/html/rfc9114)
для соединений с клиентами,
а также для соединений с проксируемыми серверами,
настраиваемых при помощи следующих директив из модуля
[Proxy](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy):
- [proxy_http3_hq](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-hq)
- [proxy_http3_max_concurrent_streams](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-max-concurrent-streams)
- [proxy_http3_max_table_capacity](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-max-table-capacity)
- [proxy_http3_stream_buffer_size](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-stream-buffer-size)
- [proxy_http_version](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version)
- [proxy_pass](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass)
- [proxy_quic_active_connection_id_limit](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-quic-active-connection-id-limit)
- [proxy_quic_gso](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-quic-gso)
- [proxy_quic_host_key](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-quic-host-key)
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_v3_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
## Пример конфигурации
```nginx
http {
log_format quic '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" "$http3"';
access_log logs/access.log quic;
server {
# для лучшей совместимости рекомендуется
# использовать одинаковый порт для http/3 и https
listen 8443 quic reuseport;
listen 8443 ssl;
ssl_certificate certs/example.com.crt;
ssl_certificate_key certs/example.com.key;
location / {
# используется для объявления о поддержке http/3
add_header Alt-Svc 'h3=":8443"; ma=86400';
}
}
}
```
#### NOTE
Чтобы принимать HTTP/3-соединения по TLS, необходимо наличие поддержки
протокола TLSv1.3, появившейся в [OpenSSL](http://www.openssl.org/) версии
1.1.1.
Для поддержки 0-RTT нужна библиотека OpenSSL версии 3.5.1 или выше. Также
возможно использование библиотек [BoringSSL](https://boringssl.googlesource.com/boringssl/),
[LibreSSL](https://www.libressl.org) или
[QuicTLS](https://github.com/quictls/openssl).
До версии 1.29.1 поддержка 0-RTT не могла быть разрешена при использовании
OpenSSL независимо от значения директивы [ssl_early_data](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-early-data).
Для запросов HTTP/3, если заголовок `Host` не передан, переменная
`$http_host` инициализируется значением псевдозаголовка
`:authority`.
Кроме того, опцию `reuseport` можно указать только в одной из директив
`listen ... quic` на сервере.
Остальные директивы `listen ... quic` должны быть указаны без нее.
## Директивы
### http3
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `http3` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию | `http3 on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает согласование протокола HTTP/3.
### http3_hq
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `http3_hq` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `http3_hq off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает согласование протокола HTTP/0.9, используемого в [функциональных тестах QUIC](https://github.com/marten-seemann/quic-interop-runner).
#### WARNING
Включайте этот режим только для запуска специализированных тестов,
которым в явной форме необходим данный режим.
### http3_max_concurrent_streams
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `http3_max_concurrent_streams` число; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `http3_max_concurrent_streams 128;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Инициализирует настройки HTTP/3 и QUIC,
а также задает максимальное число параллельных HTTP/3-потоков в соединении.
### http3_max_table_capacity
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `http3_max_table_capacity` число; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Значение по умолчанию | `http3_max_table_capacity 4096;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Определяет емкость [динамической таблицы](https://www.ietf.org/archive/id/draft-ietf-quic-qpack-20.html#name-dynamic-table)
для серверных соединений.
#### NOTE
Похожая директива [proxy_http3_max_table_capacity](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-max-table-capacity)
задает это значение для прокси-соединений.
Чтобы избежать ошибок, использование динамической таблицы
отключается при включенном кэшировании в режиме проксирования.
### http3_stream_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `http3_stream_buffer_size` размер; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `http3_stream_buffer_size 64k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает [размер](https://angie.software//angie/docs/configuration/configfile.md#syntax) буфера,
используемого для чтения и записи QUIC-потоков.
### quic_active_connection_id_limit
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `quic_active_connection_id_limit` число; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `quic_active_connection_id_limit 2;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Устанавливает значение транспортного параметра QUIC `active_connection_id_limit`. Это максимальное значение ID соединений, возможное для хранения на сервере.
### quic_bpf
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `quic_bpf` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `quic_bpf off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | main |
Разрешает маршрутизацию пакетов QUIC при помощи [eBPF](https://ebpf.io/). Если маршрутизация включена, то обеспечивается поддержка миграции QUIC-соединений.
#### NOTE
Директива поддерживается только на Linux 5.7+.
### quic_gso
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `quic_gso` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `quic_gso off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает отправку оптимизированного пакетного режима при помощи segmentation offloading.
#### NOTE
Оптимизированная отправка поддерживается только на Linux с поддержкой `UDP_SEGMENT`.
### quic_host_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `quic_host_key` файл; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает файл с секретным ключом, применяемым при шифровании stateless reset и address validation токенов. По умолчанию создается случайный ключ при каждой перезагрузке. Токены, созданные при помощи старых ключей, не принимаются.
### quic_retry
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `quic_retry` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `quic_retry off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает функциональность [QUIC Address Validation](https://datatracker.ietf.org/doc/html/rfc9000#name-address-validation), в том числе отправку нового токена в Retry-пакете или NEW_TOKEN frame и валидацию токена, полученного в Initial-пакете.
## Встроенные переменные
Модуль http_v3 поддерживает следующие встроенные переменные:
### `$http3`
согласованный идентификатор протокола:
| `h3` | для HTTP/3-соединений |
|--------|-------------------------------------|
| `hq` | для hq-соединений |
| `""` | пустая строка для остальных случаев |
### `$quic_connection`
порядковый номер QUIC-соединения
# https://angie.software/angie/docs/configuration/modules/http/http_xslt.md
# XSLT
Фильтр, преобразующий XML-ответ с помощью одного или нескольких XSLT-шаблонов.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_xslt_module`.
В наших репозиториях модуль собран [динамически](https://angie.software//angie/docs/installation/index.md#install-dynamicmodules) и
доступен отдельным пакетом `angie-module-xslt` или `angie-pro-module-xslt`.
#### NOTE
Для этого модуля нужны библиотеки [libxml2](http://xmlsoft.org/) и [libxslt](http://xmlsoft.org/XSLT/).
## Пример конфигурации
```nginx
location / {
xml_entities /site/dtd/entities.dtd;
xslt_stylesheet /site/xslt/one.xslt param=value;
xslt_stylesheet /site/xslt/two.xslt;
}
```
## Директивы
### xml_entities
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `xml_entities` путь; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл DTD, в котором описаны символьные сущности. Этот файл компилируется на стадии конфигурации. По техническим причинам модуль не имеет возможности использовать внешнее подмножество, заданное в обрабатываемом XML, поэтому оно игнорируется, а вместо него используется специально заданный файл. В этом файле не нужно описывать структуру XML, достаточно только объявления необходимых символьных сущностей, например:
```xml
```
### xslt_last_modified
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `xslt_last_modified` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `xslt_last_modified off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет сохранить поле заголовка `Last-Modified` исходного ответа во время XSLT-преобразований для лучшего кэширования ответов.
По умолчанию поле заголовка удаляется, так как содержимое ответа изменяется во время преобразования и может содержать динамически созданные элементы или части, которые изменились независимо от исходного ответа.
### xslt_param
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `xslt_param` параметр значение; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает параметры для XSLT-шаблонов. Значение рассматривается как выражение XPath. В значении можно использовать переменные. Если нужно передать в шаблон строковое значение, можно воспользоваться директивой [xslt_string_param](#xslt-string-param).
Директив `xslt_param` может быть несколько. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы `xslt_param` и [xslt_string_param](#xslt-string-param).
### xslt_string_param
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `xslt_string_param` параметр значение; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает строковые параметры для XSLT-шаблонов. Выражения XPath в значении параметра не интерпретируются. В значении можно использовать переменные.
Директив `xslt_string_param` может быть несколько. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы [xslt_param](#xslt-param) и `xslt_string_param`.
### xslt_stylesheet
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `xslt_stylesheet` шаблон [параметр=значение ...]; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Задает XSLT-шаблон и необязательные параметры для этого шаблона. Шаблон компилируется на стадии конфигурации.
Параметры можно задавать как по отдельности, так и группировать в одной строке, разделяя символом ":". Если же в самих параметрах встречается символ ":", то его нужно экранировать в виде "%3A". Кроме того, libxslt требует, чтобы параметры, содержащие не только алфавитно-цифровые символы, были заключены в одинарные или двойные кавычки, например:
```console
param1='http%3A//www.example.com':param2=value2
```
В описании параметров можно использовать переменные, например, целая строка параметров может быть взята из одной переменной:
```nginx
location / {
xslt_stylesheet /site/xslt/one.xslt
$arg_xslt_params
param1='$value1':param2=value2
param3=value3;
}
```
Можно указать несколько шаблонов — в этом случае они будут применяться последовательно в порядке их описания.
### xslt_types
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `xslt_types` mime-тип ...; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `xslt_types text/xml;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает преобразования в ответах с указанными MIME-типами в дополнение к `text/xml`. Специальное значение `*` соответствует любому MIME-типу. Если в результате преобразования выдается HTML-ответ, то его MIME-тип меняется на `text/html`.
# https://angie.software/angie/docs/configuration/modules/stream.md
# Потоковый модуль
Базовый потоковый модуль реализует основную функциональность для обработки TCP-
и UDP-соединений: это определение серверных блоков, маршрутизация трафика,
настройка проксирования, поддержка SSL/TLS и управление подключениями для
потоковых сервисов, таких как базы данных, DNS и другие протоколы, работающие на
основе TCP и UDP.
Остальные модули этого раздела расширяют эту функциональность, позволяя гибко
настраивать и оптимизировать работу потокового сервера под различные сценарии и
требования.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑stream`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
## Пример конфигурации
```nginx
worker_processes auto;
error_log /var/log/angie/error.log info;
events {
worker_connections 1024;
}
stream {
upstream backend {
hash $remote_addr consistent;
server backend1.example.com:12345 weight=5;
server 127.0.0.1:12345 max_fails=3 fail_timeout=30s;
server unix:/tmp/backend3;
}
upstream dns {
server 192.168.0.1:53535;
server dns.example.com:53;
}
server {
listen 12345;
proxy_connect_timeout 1s;
proxy_timeout 3s;
proxy_pass backend;
}
server {
listen 127.0.0.1:53 udp reuseport;
proxy_timeout 20s;
proxy_pass dns;
}
server {
listen [::1]:12345;
proxy_pass unix:/tmp/stream.socket;
}
}
```
## Директивы
### listen
#### Versionchanged
Изменено в версии 1.10.0.
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `listen` адрес[:порт] [`ssl`] [`udp`] [`proxy_protocol`] [`setfib=`число] [`fastopen=`число] [`backlog=`число] [`rcvbuf=`размер] [`sndbuf=`размер] [`accept_filter=`фильтр] [`deferred`] [`bind`] [`ipv6only=``on` | `off`] [`reuseport`] [`so_keepalive=`on|off|[`keepidle`]:[`keepintvl`]:[`keepcnt`]]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server |
Задает адрес и порт для сокета, на котором сервер будет принимать соединения. Можно указать только порт, и тогда Angie будет слушать на всех доступных IPv4-интерфейсах (и IPv6, если он включен). Кроме того, адрес может быть именем хоста, например:
```nginx
listen 127.0.0.1:12345;
listen *:12345;
listen 12345; # то же, что и *:12345
listen localhost:12345;
```
IPv6-адреса задаются в квадратных скобках:
```nginx
listen [::1]:12345;
listen [::]:12345;
```
UNIX-сокеты задаются префиксом `unix:`
```nginx
listen unix:/var/run/angie.sock;
```
Диапазоны портов задаются при помощи указания первого и последнего порта через дефис:
```nginx
listen 127.0.0.1:12345-12399;
listen 12345-12399;
```
#### NOTE
Разные серверы должны слушать на разных парах адрес:порт.
| `ssl` | указывает на то, что все соединения, принимаемые на данном слушающем сокете, должны работать в режиме SSL. |
|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `udp` | конфигурирует слушающий сокет для работы с датаграммами. Для обработки пакетов с одного адреса и порта в рамках одной сессии необходимо также указывать параметр reuseport. |
| `proxy_protocol` | указывает на то, что все соединения, принимаемые на данном порту, должны использовать протокол PROXY. |
В директиве `listen` можно также указать несколько дополнительных параметров, специфичных для связанных с сокетами системных вызовов.
| `setfib=`число | устанавливает связанную таблицу маршрутизации, FIB (параметр
`SO_SETFIB`) для слушающего сокета. Пока это работает только на
FreeBSD. |
|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `fastopen=`число | включает "TCP Fast Open" для слушающего сокета и [ограничивает](https://datatracker.ietf.org/doc/html/rfc7413#section-5.1) максимальную длину очереди соединений, которые еще не завершили процесс трехстороннего рукопожатия.
#### WARNING
Не включайте "TCP Fast Open", не убедившись, что сервер может адекватно обрабатывать [многократное получение](https://datatracker.ietf.org/doc/html/rfc7413#section-6.1) одного и того же SYN-пакета с данными. |
| `backlog=`число | задает параметр backlog в вызове listen(), который ограничивает максимальный размер очереди ожидающих приема соединений. По умолчанию backlog устанавливается равным -1 для FreeBSD, DragonFly BSD и macOS, и 511 для других платформ. |
| `rcvbuf=`размер | задает размер буфера приема (параметр SO_RCVBUF) для слушающего сокета. |
| `sndbuf=`размер | задает размер буфера передачи (параметр SO_SNDBUF) для слушающего сокета. |
| `accept_filter=`фильтр | задает имя принимающего фильтра (параметр `SO_ACCEPTFILTER`) для
слушающего сокета, который фильтрует входящие соединения перед их
передачей в `accept()`. Работает только на FreeBSD и NetBSD 5.0+.
Допустимые значения: `dataready` и `httpready`. |
| `deferred` | указывает использовать отложенный `accept()` (параметр
`TCP_DEFER_ACCEPT`) на Linux. |
| `bind` | указывает, что для данного слушающего сокета нужно делать bind()
отдельно. Это нужно потому, что если описаны несколько директив
`listen` с одинаковым портом, но разными адресами, и одна из
директив `listen` слушает на всех адресах для данного порта
(\*:порт), то Angie сделает bind() только на \*:порт. Необходимо
заметить, что в этом случае для определения адреса, на который пришло
соединение, делается системный вызов getsockname(). Если же
используются параметры setfib, fastopen, backlog, rcvbuf,
sndbuf, accept_filter, deferred, ipv6only, reuseport или
so_keepalive, то для данной пары адрес:порт всегда делается отдельный
вызов bind(). |
| `ipv6only=on` | `off` | определяет (через параметр сокета `IPV6_V6ONLY`), будет ли слушающий на wildcard-адресе [::] IPv6-сокет принимать только IPv6-соединения, или же одновременно IPv6- и IPv4-соединения. По умолчанию параметр включен. Установить его можно только один раз на старте. |
| `reuseport` | указывает, что нужно создавать отдельный слушающий сокет для каждого рабочего процесса (через параметр сокета SO_REUSEPORT для Linux 3.9+ и DragonFly BSD или SO_REUSEPORT_LB для FreeBSD 12+), позволяя ядру распределять входящие соединения между рабочими процессами. В настоящий момент это работает только на Linux 3.9+, DragonFly BSD и FreeBSD 12+.
#### WARNING
Ненадлежащее использование параметра reuseport
может быть небезопасно. |
| `multipath` | включает прием соединений по протоколу [Multipath TCP](https://en.wikipedia.org/wiki/Multipath_TCP) (MPTCP),
поддерживаемому в ядре Linux с версии 5.6.
Параметр **несовместим** с `udp`. |
`so_keepalive=on` | `off` | [`keepidle`]:[`keepintvl`]:[`keepcnt`]
Конфигурирует для слушающего сокета поведение "TCP keepalive".
| `''` | если параметр опущен, для сокета будут действовать настройки операционной системы |
|--------|-------------------------------------------------------------------------------------|
| `on` | для сокета включается параметр SO_KEEPALIVE |
| `off` | для сокета параметр SO_KEEPALIVE выключается |
Некоторые операционные системы поддерживают настройку параметров "TCP keepalive"
на уровне сокета посредством параметров `TCP_KEEPIDLE`, `TCP_KEEPINTVL` и
`TCP_KEEPCNT`. На таких системах их можно сконфигурировать с помощью параметров
`keepidle`, `keepintvl` и `keepcnt`. Один или два параметра могут быть опущены,
в таком случае для соответствующего параметра сокета будут действовать
стандартные системные настройки.
Например,
```nginx
so_keepalive=30m::10
```
установит таймаут бездействия (`TCP_KEEPIDLE`) в 30 минут, для интервала проб (`TCP_KEEPINTVL`) будет действовать стандартная системная настройка, а счетчик проб (`TCP_KEEPCNT`) будет равен 10.
### preread_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `preread_buffer_size` размер; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `preread_buffer_size 16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает размер буфера [предварительного чтения](https://angie.software//angie/docs/configuration/processing.md#stream-sessions).
### preread_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `preread_timeout` время; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `preread_timeout 30s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает время фазы [предварительного чтения](https://angie.software//angie/docs/configuration/processing.md#stream-sessions).
### proxy_protocol_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_protocol_timeout` время; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `proxy_protocol_timeout 30s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает время для завершения операции чтения заголовка протокола PROXY. Если по истечении этого времени заголовок полностью не получен, соединение закрывается.
### resolver
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `resolver` адрес ... [`valid=`время] [`ipv4=``on` | `off`] [`ipv6=``on` | `off`] [`status_zone=`зона]; |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server, upstream |
Задает серверы DNS, используемые для преобразования имен вышестоящих серверов в адреса, например:
```nginx
resolver 127.0.0.53 [::1]:5353;
```
Адрес может быть указан в виде доменного имени или IP-адреса, и необязательного порта.
Если порт не указан, используется порт 53. Серверы DNS опрашиваются циклически.
#### NOTE
Рекомендуется использовать локальный доверенный резолвер, например
`127.0.0.53` (systemd-resolved), а не публичный (например, `8.8.8.8`).
Публичные резолверы раскрывают DNS-запросы третьим сторонам и повышают
риск атак с подменой кэша.
#### NOTE
Значение директивы наследуется вложенными блоками
и может быть переопределено в них при необходимости.
В пределах одного блока допустимо указывать директиву только один раз.
Если она повторяется, действует последнее определение.
По умолчанию Angie кэширует ответы, используя значение TTL из ответа DNS. Если
директива `resolver` не указана и не выполняются динамические DNS-запросы
(например, при использовании фиксированных имен в [Proxy](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#stream-proxy) без
переменных), указание резолвера не требуется: имена будут разрешены при запуске
с помощью системного резолвера. Необязательный параметр `valid` позволяет
это переопределить:
| `valid` | *необязательный* параметр, позволяет переопределить срок кэширования ответа |
|-----------|--------------------------------------------------------------------------------|
```nginx
resolver 127.0.0.53 [::1]:5353 valid=30s;
```
По умолчанию Angie будет искать как IPv4-, так и IPv6-адреса при преобразовании имен в адреса.
| `ipv4=off` | запрещает поиск IPv4-адресов |
|--------------|--------------------------------|
| `ipv6=off` | запрещает поиск IPv6-адресов |
| `status_zone` | *необязательный* параметр;
включает сбор метрик запросов и ответов DNS-сервера
([/status/resolvers/<зона>](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-resolvers))
в указанной зоне |
|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### resolver_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `resolver_timeout` время; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `resolver_timeout 30s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server, upstream |
Задает таймаут для преобразования имени в адрес, например:
```nginx
```
resolver_timeout 5s;
### error_log_user_tag
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `error_log_user_tag` значение; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Добавляет тег, зависящий от сессии, в записи [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log). Значение является
[сложным значением](https://angie.software//angie/docs/configuration/configfile.md#syntax) и может содержать переменные. Директива может
задаваться несколько раз для добавления нескольких тегов. Теги используются в
фильтрах `filter=tag:` директивы [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log).
### server
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `server` { ... } |
|------------------------------------------------------------------------------------------|--------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream |
Задает конфигурацию для сервера.
### server_name
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `server_name` имя ...; |
|------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию | `server_name "";` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server |
Задает имена виртуального сервера.
#### WARNING
В модуле `stream` директива `server_name` основана на Server Name
Indication ([SNI](https://angie.software//angie/docs/configuration/ssl.md#sni)) и работает только с TLS-соединениями. Для
использования необходимо [настроить TLS-терминацию](https://angie.software//angie/docs/configuration/ssl.md#ssl-config) или
[включить TLS preread](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#stream-ssl-preread) в соответствующем блоке
`server`.
Пример конфигурации:
```nginx
server {
listen 443 ssl;
server_name example.com www.example.com;
ssl_certificate /etc/angie/cert.pem;
ssl_certificate_key /etc/angie/key.pem;
}
```
Первое указанное имя становится основным именем сервера.
Имена серверов могут включать звездочку (`*`),
заменяющую первую или последнюю часть имени:
```nginx
server {
server_name example.com *.example.com www.example.*;
}
```
Такие имена называются подстановочными (wildcard).
Также можно использовать регулярные выражения в именах серверов,
предваряя имя тильдой (`~`):
```none
server {
server_name www.example.com ~^www\d+\.example\.com$;
}
```
Регулярные выражения могут включать захватываемые группы,
которые можно использовать в других директивах:
```nginx
server {
server_name ~^(www\.)?(.+)$;
proxy_pass www.$2:12345;
}
```
Именованные захваты в регулярных выражениях создают переменные, которые можно
использовать в других директивах:
```nginx
server {
server_name ~^(www\.)?(?.+)$;
proxy_pass www.$domain:12345;
}
```
Если параметр директивы установлен на `$hostname`, будет вставлено имя
хоста машины.
При поиске виртуального сервера по имени, если имя совпадает с более чем одним
из указанных вариантов (например, совпадают и шаблонное имя, и регулярное
выражение), будет выбрано первое совпавшее имя в следующем порядке приоритета:
- Точное имя
- Самое длинное шаблонное имя, начинающееся с звездочки, например,
`*.example.com`
- Самое длинное шаблонное имя, заканчивающееся звездочкой, например,
`mail.*`
- Первое совпавшее регулярное выражение (в порядке появления в конфигурационном
файле)
### server_names_hash_bucket_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `server_names_hash_bucket_size` размер; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `server_names_hash_bucket_size 32|64|128;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream |
Задает размер корзины для хэш-таблиц имен серверов. Значение по умолчанию
зависит от размера кэш-линии процессора.
### server_names_hash_max_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `server_names_hash_max_size` размер; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `server_names_hash_max_size 512;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream |
Задает максимальный размер хэш-таблиц имен серверов.
### status_zone
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `status_zone` зона | ключ `zone=`зона[:число]; |
|------------------------------------------------------------------------------------------|--------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server |
Выделяет зону разделяемой памяти для сбора метрик
[/status/stream/server_zones/<зона>](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-server-zones).
Несколько контекстов `server`
могут совместно использовать одну и ту же зону для сбора данных.
Синтаксис с одним значением зоны
объединяет все метрики для текущего контекста в одну зону разделяемой памяти:
```nginx
server {
listen 80;
server_name *.example.com;
status_zone single;
# ...
}
```
Альтернативный синтаксис позволяет задавать следующие параметры:
| значение | Строка с переменными, значение которой определяет группировку подключений
в зоне. Все подключения, дающие одинаковые значения после подстановки,
объединяются в одну группу. Если подстановка возвращает пустое значение,
метрики не обновляются. |
|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| зона | Имя зоны разделяемой памяти. |
| число (необязательный) | Максимальное количество отдельных групп для сбора метрик.
Если новые значения ключа превышают этот лимит, они объединяются в группу zone.
Значение по умолчанию — 1. |
В следующем примере все соединения с одинаковым значением `$server_addr`
группируются в `host_zone`. Метрики собираются отдельно для каждого
уникального значения `$server_addr` до тех пор, пока количество групп
метрик не достигнет 10. После этого любые новые значения `$server_addr`
будут добавляться в группу `server_zone`:
```nginx
stream {
upstream backend {
server 192.168.0.1:3306;
server 192.168.0.2:3306;
# ...
}
server {
listen 3306;
proxy_pass backend;
status_zone $server_addr zone=server_zone:10;
}
}
```
Результирующие метрики разделяются по отдельным серверам в выводе API.
#### NOTE
Эти метрики собираются, только если задан `status_zone`. Без него
сервер не отображается в [/status/stream/server_zones/<зона>](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-server-zones),
в [виджете «TCP/UDP Zones»](https://angie.software//angie/docs/configuration/monitoring.md#tcp-udp-zones-widget)
и в выводе [Prometheus](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus),
и предупреждение при этом не выводится.
### stream
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `stream` { ... } |
|------------------------------------------------------------------------------------------|--------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | main |
Предоставляет контекст конфигурационного файла, в котором указываются директивы stream-сервера.
### tcp_nodelay
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `tcp_nodelay` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `tcp_nodelay on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Разрешает или запрещает использование параметра `TCP_NODELAY`. Параметр включается как для клиентских соединений, так и для соединений с проксируемыми серверами.
### variables_hash_bucket_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `variables_hash_bucket_size` размер; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `variables_hash_bucket_size 64;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream |
Задает размер корзины в хэш-таблице переменных. Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
### variables_hash_max_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `variables_hash_max_size` размер; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `variables_hash_max_size 1024;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream |
Задает максимальный размер хэш-таблиц переменных. Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
## Встроенные переменные
Базовый потоковый модуль поддерживает встроенные переменные:
### `$angie_version`
версия Angie
### `$binary_remote_addr`
адрес клиента в бинарном виде, длина значения всегда 4 байта для IPv4-адресов или 16 байт для IPv6-адресов
### `$bytes_received`
число байт, полученных от клиента
### `$bytes_sent`
число байт, переданных клиенту
### `$connection`
порядковый номер соединения
### `$hostname`
имя хоста
### `$msec`
текущее время в секундах с точностью до миллисекунд
### `$nginx_version`
версия nginx
### `$pid`
номер (PID) рабочего процесса
### `$protocol`
протокол, используемый для работы с клиентом: TCP или UDP
### `$proxy_protocol_addr`
адрес клиента, полученный из заголовка протокола PROXY.
Протокол PROXY должен быть предварительно включен при помощи установки параметра proxy_protocol в директиве [listen](#s-listen).
### `$proxy_protocol_port`
порт клиента, полученный из заголовка протокола PROXY.
Протокол PROXY должен быть предварительно включен при помощи установки параметра proxy_protocol в директиве [listen](#s-listen).
### `$proxy_protocol_server_addr`
адрес сервера, полученный из заголовка протокола PROXY.
Протокол PROXY должен быть предварительно включен при помощи установки параметра proxy_protocol в директиве [listen](#s-listen).
### `$proxy_protocol_server_port`
порт сервера, полученный из заголовка протокола PROXY.
Протокол PROXY должен быть предварительно включен при помощи установки параметра proxy_protocol в директиве [listen](#s-listen).
### `$proxy_protocol_tlv_<имя>`
TLV, полученный из заголовка протокола PROXY. Имя может быть именем типа TLV или его числовым значением. В последнем случае значение задается в шестнадцатеричном виде и должно начинаться с 0x:
```none
$proxy_protocol_tlv_alpn
$proxy_protocol_tlv_0x01
```
SSL TLV могут также быть доступны как по имени типа TLV, так и по его числовому значению, оба должны начинаться с `ssl_`:
```none
$proxy_protocol_tlv_ssl_version
$proxy_protocol_tlv_ssl_0x21
```
Поддерживаются следующие имена типов TLV:
* `alpn (0x01)` - протокол более высокого уровня, используемый поверх соединения
* `authority (0x02)` - значение имени хоста, передаваемое клиентом
* `unique_id (0x05)` - уникальный идентификатор соединения
* `netns (0x30)` - имя пространства имен
* `ssl (0x20)` - структура SSL TLV в бинарном виде
Поддерживаются следующие имена типов SSL TLV:
* `ssl_version (0x21)` - версия SSL, используемая в клиентском соединении
* `ssl_cn (0x22)` - Common Name сертификата
* `ssl_cipher (0x23)` - имя используемого шифра
* `ssl_sig_alg (0x24)` - алгоритм, используемый для подписи сертификата
* `ssl_key_alg (0x25)` - алгоритм публичного ключа
Также поддерживается следующее специальное имя типа SSL TLV:
* `ssl_verify` - результат проверки клиентского сертификата: 0, если клиент предоставил сертификат и он был успешно верифицирован, либо ненулевое значение
Протокол PROXY должен быть предварительно включен при помощи установки параметра proxy_protocol в директиве [listen](#s-listen).
### `$remote_addr`
адрес клиента
### `$remote_port`
порт клиента
### `$server_addr`
адрес сервера, принявшего соединение.
Получение значения этой переменной обычно требует одного системного вызова. Чтобы избежать системного вызова, в директивах [listen](#s-listen) следует указывать адреса и использовать параметр `bind`.
### `$server_port`
порт сервера, принявшего соединение
### `$session_time`
длительность сессии в секундах с точностью до миллисекунд
### `$status`
статус сессии, может принимать одно из следующих значений:
| `200` | сессия завершена успешно |
|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `400` | невозможно разобрать данные, полученные от клиента, например заголовок протокола PROXY |
| `403` | доступ запрещен, например при ограничении доступа для [определенных адресов клиентов](https://angie.software//angie/docs/configuration/modules/stream/stream_access.md#stream-access) |
| `500` | внутренняя ошибка сервера |
| `502` | плохой шлюз, например если невозможно выбрать сервер группы или сервер недоступен |
| `503` | сервис недоступен, например при ограничении по [числу соединений](https://angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#stream-limit-conn) |
### `$time_iso8601`
локальное время в формате по стандарту ISO 8601
### `$time_local`
локальное время в Common Log Format
# https://angie.software/angie/docs/configuration/modules/stream/stream_access.md
# Access
Модуль позволяет ограничить доступ для определенных адресов клиентов.
## Пример конфигурации
```nginx
server {
...
deny 192.168.1.1;
allow 192.168.1.0/24;
allow 10.1.1.0/16;
allow 2001:0db8::/32;
deny all;
}
```
Правила проверяются в порядке их записи до первого соответствия. В данном примере доступ разрешен только для IPv4-сетей `10.1.1.0/16` и `192.168.1.0/24`, кроме адреса `192.168.1.1`, и для IPv6-сети `2001:0db8::/32`.
## Директивы
### allow
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `allow` адрес | CIDR | `unix:` | `all`; |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Разрешает доступ для указанной сети или адреса. Если указано специальное значение `unix:`, разрешает доступ для всех UNIX-сокетов.
### deny
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `deny` адрес | CIDR | `unix:` | `all`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Запрещает доступ для указанной сети или адреса. Если указано специальное значение `unix:`, запрещает доступ для всех UNIX-сокетов.
# https://angie.software/angie/docs/configuration/modules/stream/stream_acme.md
# ACME
#### Versionadded
Добавлено в версии 1.10.0.
Позволяет автоматически получать сертификаты
с использованием протокола [ACME](https://datatracker.ietf.org/doc/html/rfc8555)
для серверов, определенных в контексте `stream`.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild)
модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-stream_acme_module`
(также требуется `--with-http_acme_module`).
В пакетах и образах из [наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
#### NOTE
Для корректной работы блок `stream`
должен располагаться после блока `http`.
Это связано с тем, что потоковый модуль использует определения клиентов,
созданные при разборе HTTP-конфигурации.
## Пример конфигурации
В этом примере сертификаты, полученные ACME-клиентом `example`
(объявленным в блоке `http`), защищают TCP-сервер;
по умолчанию используется HTTP-проверка:
```nginx
# HTTP-часть
http {
resolver 127.0.0.53;
# ACME-клиент для потоковой части
acme_client example https://acme-v02.api.letsencrypt.org/directory;
# Сервер для HTTP-проверки
server {
listen 80;
return 444;
}
}
# Потоковая часть
stream {
server {
listen 12345 ssl;
proxy_pass backend_upstream;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
server_name example.com www.example.com;
acme example; # ссылка на ACME-клиент, определенный в HTTP-части
}
upstream backend_upstream {
server 127.0.0.1:54321;
}
}
```
Примеры конфигурации и инструкции по настройке, в том числе для DNS-проверки,
см. в разделе [ACME в потоковом модуле](https://angie.software//angie/docs/configuration/acme.md#acme-config-stream).
## Директивы
### acme
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `acme` имя; |
|------------------------------------------------------------------------------------------|---------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server |
Для всех доменов, указанных в директивах [server_name](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-server-name)
во всех блоках [server](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-server),
которые ссылаются на [клиент ACME](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) из HTTP-модуля с именем имя,
будет получен единый сертификат;
если изменится конфигурация `server_name`,
сертификат будет обновлен для учета изменений.
При каждом запуске Angie для всех доменов,
у которых отсутствует действующий сертификат, запрашиваются новые сертификаты.
Возможные причины включают истечение срока действия сертификатов,
отсутствие файлов или невозможность прочитать их,
а также изменения в настройках сертификатов.
#### NOTE
Сейчас домены, заданные через регулярные выражения,
не поддерживаются и будут пропускаться.
Домены со звездочкой поддерживаются только в режиме `challenge=dns`
в `acme_client`.
Эта директива может быть указана несколько раз
для загрузки сертификатов разных типов, например RSA и ECDSA:
```nginx
server {
listen 12345 ssl;
server_name example.com www.example.com;
ssl_certificate $acme_cert_rsa;
ssl_certificate_key $acme_cert_key_rsa;
ssl_certificate $acme_cert_ecdsa;
ssl_certificate_key $acme_cert_key_ecdsa;
acme rsa;
acme ecdsa;
}
```
## Встроенные переменные
### `$acme_cert_<имя>`
Содержимое последнего файла сертификата (если он есть),
полученного клиентом с этим именем.
### `$acme_cert_key_<имя>`
Содержимое файла ключа сертификата,
используемого клиентом с этим именем.
#### NOTE
Файл сертификата доступен,
только если клиент ACME получил хотя бы один сертификат,
а вот файл ключа доступен сразу после запуска.
# https://angie.software/angie/docs/configuration/modules/stream/stream_geo.md
# Geo
Создает переменные, значения которых зависят от IP-адреса клиента.
## Пример конфигурации
```nginx
geo $geo {
default 0;
127.0.0.1 2;
192.168.1.0/24 1;
10.1.0.0/16 1;
::1 2;
2001:0db8::/32 1;
}
```
## Директивы
### geo
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `geo` [$адрес] $переменная { ... } |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream |
Описывает для указанной переменной зависимость значения от IP-адреса клиента. По умолчанию адрес берется из переменной [$remote_addr](https://angie.software//angie/docs/configuration/modules/http/index.md#v-remote-addr), но его также можно получить из другой переменной, например:
```nginx
geo $arg_remote_addr $geo {
...;
}
```
#### NOTE
Поскольку переменные вычисляются только в момент использования, само по себе наличие даже большого числа объявлений переменных `geo` не влечет за собой никаких дополнительных расходов на обработку соединений.
Если значение переменной не представляет из себя правильный IP-адрес, то используется адрес "255.255.255.255".
Адреса задаются либо префиксами в формате CIDR (включая одиночные адреса), либо в виде диапазонов.
Также поддерживаются следующие специальные параметры:
| `delete` | Удаляет описанную сеть. |
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `default` | Значение переменной, если адрес клиента не соответствует ни одному из заданных адресов. При задании адресов в формате CIDR вместо `default` можно использовать `0.0.0.0/0` и `::/0`. Если параметр `default` не указан, значением по умолчанию будет пустая строка. |
| `include` | Включает файл с адресами и значениями. Включений может быть несколько. |
| `ranges` | Указывает, что адреса задаются в виде диапазонов. Этот параметр должен быть первым. Для ускорения загрузки гео-базы нужно располагать адреса в порядке возрастания. |
| `volatile` | Указывает, что переменная не кэшируется. |
Пример:
```nginx
geo $country {
default ZZ;
include conf/geo.conf;
delete 127.0.0.0/16;
127.0.0.0/24 US;
127.0.0.1/32 RU;
10.1.0.0/16 RU;
192.168.1.0/24 UK;
}
```
В файле `conf/geo.conf` могут быть такие строки:
```console
10.2.0.0/16 RU;
192.168.2.0/24 RU;
```
В качестве значения выбирается максимальное совпадение, например, для адреса `127.0.0.1` будет выбрано значение `RU`, а не `US`.
Пример описания диапазонов:
```nginx
geo $country {
ranges;
default ZZ;
127.0.0.0-127.0.0.0 US;
127.0.0.1-127.0.0.1 RU;
127.0.0.2-127.0.0.255 US;
10.1.0.0-10.1.255.255 RU;
192.168.1.0-192.168.1.255 UK;
}
```
# https://angie.software/angie/docs/configuration/modules/stream/stream_geoip.md
# GeoIP
Создает переменные, значения которых зависят от IP-адреса клиента, используя готовые базы данных [MaxMind](http://www.maxmind.com/).
При использовании баз данных с поддержкой IPv6 IPv4-адреса ищутся отображенными на IPv6.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild)
модуль необходимо включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑stream_geoip_module`.
#### NOTE
Для этого модуля нужна библиотека [MaxMind GeoIP](https://github.com/maxmind/geoip-api-c).
## Пример конфигурации
```nginx
stream {
geoip_country GeoIP.dat;
geoip_city GeoLiteCity.dat;
map $geoip_city_continent_code $nearest_server {
default example.com;
EU eu.example.com;
NA na.example.com;
AS as.example.com;
}
# ...
}
```
## Директивы
### geoip_country
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `geoip_country` файл; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream |
Задает базу данных для определения страны в зависимости от значения IP-адреса клиента. При использовании этой базы данных доступны следующие переменные:
| `$geoip_country_code` | двухбуквенный код страны, например, "RU", "US". |
|-------------------------|-------------------------------------------------------------------|
| `$geoip_country_code3` | трехбуквенный код страны, например, "RUS", "USA". |
| `$geoip_country_name` | название страны, например, "Russian Federation", "United States". |
### geoip_city
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `geoip_city` файл; |
|------------------------------------------------------------------------------------------|----------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream |
Задает базу данных для определения страны, региона и города в зависимости от значения IP-адреса клиента. При использовании этой базы данных доступны следующие переменные:
| `$geoip_city_continent_code` | двухбуквенный код континента, например, "EU", "NA". |
|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `$geoip_city_country_code` | двухбуквенный код страны, например, "RU", "US". |
| `$geoip_city_country_code3` | трехбуквенный код страны, например, "RUS", "USA". |
| `$geoip_city_country_name` | название страны, например, "Russian Federation", "United States". |
| `$geoip_dma_code` | DMA-код региона в США (также известный как "код агломерации"), согласно [геотаргетингу](https://developers.google.com/adwords/api/docs/appendix/cities-DMAregions) Google AdWords API. |
| `$geoip_latitude` | широта. |
| `$geoip_longitude` | долгота. |
| `$geoip_region` | двухсимвольный код региона страны (область, край, штат, провинция, федеральная земля и тому подобное), например, "48", "DC". |
| `$geoip_region_name` | название региона страны (область, край, штат, провинция, федеральная земля и тому подобное), например, "Moscow City", "District of Columbia". |
| `$geoip_city` | название города, например, "Moscow", "Washington". |
| `$geoip_postal_code` | почтовый индекс. |
### geoip_org
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `geoip_org` файл; |
|------------------------------------------------------------------------------------------|---------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream |
Задает базу данных для определения названия организации в зависимости от значения IP-адреса клиента. При использовании этой базы данных доступна следующая переменная:
| `$geoip_org` | название организации, например, "The University of Melbourne". |
|----------------|------------------------------------------------------------------|
# https://angie.software/angie/docs/configuration/modules/stream/stream_limit_conn.md
# Limit Conn
Позволяет ограничить число соединений по заданному ключу, в частности, число соединений с одного IP-адреса.
## Пример конфигурации
```nginx
stream {
limit_conn_zone $binary_remote_addr zone=addr:10m;
...
server {
...
limit_conn addr 1;
limit_conn_log_level error;
}
}
```
## Директивы
### limit_conn
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_conn` зона число; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает зону разделяемой памяти и максимально допустимое число соединений для одного значения ключа. При превышении этого числа сервер закроет соединение. Например, директивы
```nginx
limit_conn_zone $binary_remote_addr zone=addr:10m;
server {
...
limit_conn addr 1;
}
```
разрешают одновременно обрабатывать не более одного соединения с одного IP-адреса.
Допустимо одновременное указание нескольких директив `limit_conn`, при этом будет срабатывать любое из ограничений.
Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы `limit_conn`.
### limit_conn_dry_run
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_conn_dry_run` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `limit_conn_dry_run off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Включает режим пробного запуска. В данном режиме число соединений не ограничивается, однако в [зоне разделяемой памяти](#s-limit-conn-zone) текущее число избыточных соединений учитывается как обычно.
### limit_conn_log_level
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_conn_log_level` `info` | `notice` | `warn` | `error`; |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------|
| По умолчанию | `limit_conn_log_level error;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает желаемый уровень записи в лог случаев ограничения числа соединений.
### limit_conn_zone
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_conn_zone` ключ zone = название:размер; |
|------------------------------------------------------------------------------------------|--------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream |
Задает параметры зоны разделяемой памяти, которая хранит состояние для разных значений ключа. Состояние в частности содержит текущее число соединений. В качестве ключа может использоваться текст, переменные и их комбинации. Запросы с пустым значением ключа не учитываются.
Пример использования:
```nginx
limit_conn_zone $binary_remote_addr zone=addr:10m;
```
Здесь в качестве ключа используется IP-адрес клиента, задаваемый переменной `$binary_remote_addr`.
Длина значения `$binary_remote_addr` равна 4 байтам для IPv4-адресов или 16 байтам для IPv6-адресов. При этом размер состояния всегда равен 32 или 64 байтам на 32-битных платформах и 64 байтам на 64-битных. В зоне размером 1 мегабайт может разместиться около 32 тысяч состояний размером 32 байта или 16 тысяч состояний размером 64 байта. При переполнении зоны сервер закроет соединение.
## Встроенные переменные
### `$limit_conn_status`
хранит результат ограничения числа соединений: `PASSED`, `REJECTED` или `REJECTED_DRY_RUN`
# https://angie.software/angie/docs/configuration/modules/stream/stream_log.md
# Log
Модуль записывает логи запросов в указанном формате.
## Пример конфигурации
```nginx
log_format basic '$remote_addr [$time_local] '
'$protocol $status $bytes_sent $bytes_received '
'$session_time';
access_log /spool/logs/angie-access.log basic buffer=32k;
```
## Директивы
### access_log
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `access_log` путь [формат [`buffer=`размер] [gzip[=степень]] [`flush=`время] [`if=`условие]];
`access_log` `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `access_log off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает путь, формат и настройки буферизованной записи в лог. На одном уровне конфигурации может использоваться несколько логов. Запись в [syslog](https://angie.software//angie/docs/configuration/processing.md#syslog-logging) настраивается указанием префикса "syslog:" в первом параметре. Специальное значение off отменяет все директивы access_log для текущего уровня.
Если задан размер буфера с помощью параметра `buffer` или указан параметр `gzip`, то запись будет буферизованной.
#### WARNING
Размер буфера должен быть не больше размера атомарной записи в дисковый файл. Для FreeBSD этот размер неограничен.
При включенной буферизации данные записываются в файл:
* если очередная строка лога не помещается в буфер;
* если данные в буфере находятся дольше интервала времени, заданного параметром `flush`;
* при [переоткрытии лог-файла](https://angie.software//angie/docs/configuration/runtime.md#log-rotation) или завершении рабочего процесса.
Если задан параметр `gzip`, то буфер будет сжиматься перед записью в файл. Степень сжатия может быть задана в диапазоне от 1 (быстрее, но хуже сжатие) до 9 (медленнее, но лучше сжатие). По умолчанию используются буфер размером 64К байт и степень сжатия 1. Данные сжимаются атомарными блоками, и в любой момент времени лог-файл может быть распакован или прочитан с помощью утилиты "zcat".
Пример:
```nginx
access_log /path/to/log.gz basic gzip flush=5m;
```
#### NOTE
Для поддержки gzip-сжатия логов Angie должен быть собран с библиотекой zlib.
В пути файла можно использовать переменные, но такие логи имеют некоторые ограничения:
* [пользователь](https://angie.software//angie/docs/configuration/modules/core.md#user), с правами которого работают рабочие процессы, должен иметь права на создание файлов в каталоге с такими логами;
* не работает буферизация;
* файл открывается для каждой записи в лог и сразу же после записи закрывается. Следует однако иметь в виду, что поскольку дескрипторы часто используемых файлов могут храниться в кэше, то при ротации логов в течение времени, заданного параметром valid директивы [open_log_file_cache](https://angie.software//angie/docs/configuration/modules/http/http_log.md#open-log-file-cache), запись может продолжаться в старый файл.
Параметр if включает условную запись в лог. Сессия не будет записываться в лог, если результатом вычисления условия является "0" или пустая строка.
### log_format
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `log_format` имя [`escape=``default` | `json` | `none`] строка ...; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream |
Задает формат лога, например:
```nginx
log_format proxy '$remote_addr [$time_local] '
'$protocol $status $bytes_sent $bytes_received '
'$session_time "$upstream_addr" '
'"$upstream_bytes_sent" "$upstream_bytes_received" "$upstream_connect_time"';
```
Параметр `escape` позволяет задать экранирование символов `json` или `default` в переменных, по умолчанию используется `default`. Значение `none` отключает экранирование символов.
При использовании `default` символы """, "\\", а также символы со значениями меньше 32 или больше 126 экранируются как "\\xXX". Если значение переменной не найдено, то в качестве значения в лог будет записываться дефис "-".
При использовании `json` экранируются все символы, недопустимые в JSON строках: символы """ и "\\" экранируются как "\\"" и "\\\\", символы со значениями меньше 32 экранируются как "\\n", "\\r", "\\t", "\\b", "\\f" или "\\u00XX".
### open_log_file_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `open_log_file_cache` `max=`N [`inactive=`время] [`min_uses=`N] [`valid=`время]; |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| По умолчанию | `open_log_file_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает кэш, в котором хранятся дескрипторы файлов часто используемых логов, имена которых заданы с использованием переменных. Параметры:
| `max` | Задает максимальное число дескрипторов в кэше; при переполнении кэша наименее востребованные (LRU) дескрипторы закрываются. |
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `inactive` | Задает время, после которого кэшированный дескриптор закрывается, если к нему не было обращений в течение этого времени; по умолчанию — 10 секунд. |
| `min_uses` | Задает минимальное число использований файла в течение времени, заданного параметром `inactive`, после которого дескриптор файла будет оставаться открытым в кэше; по умолчанию — 1. |
| `valid` | Указывает, через какое время нужно проверять, что файл еще существует под тем же именем; по умолчанию — 60 секунд. |
| `off` | Запрещает кэширование. |
Пример использования:
```nginx
open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;
```
# https://angie.software/angie/docs/configuration/modules/stream/stream_map.md
# Map
Создает переменные, значения которых зависят от значений других переменных.
## Пример конфигурации
```nginx
map $remote_addr $limit {
127.0.0.1 "";
default $binary_remote_addr;
}
limit_conn_zone $limit zone=addr:10m;
limit_conn addr 1;
```
## Директивы
### map
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `map` строка $переменная { ... }; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream |
Создает новую переменную.
Ее значение зависит от первого параметра, заданного строкой с переменными,
например:
```nginx
set $var1 "foo";
set $var2 "bar";
map $var1$var2 $new_variable {
default "foobar_value";
}
```
Здесь переменная `$new_variable` будет иметь значение,
составленное из двух переменных `$var1` и `$var2`,
или значение по умолчанию, если эти переменные не определены.
#### NOTE
Поскольку переменные вычисляются только в момент использования, само по себе наличие даже большого числа объявлений переменных `map` не влечет за собой никаких дополнительных расходов на обработку запросов.
Параметры внутри блока `map` задают соответствие между исходными и результирующими значениями.
Исходные значения задаются строками или регулярными выражениями.
Строки проверяются без учета регистра.
Перед регулярным выражением ставится символ `~`, если при сравнении
следует учитывать регистр символов, либо символы `~*`, если регистр
символов учитывать не нужно. Регулярное выражение может содержать именованные и
позиционные группы захвата, которые могут затем использоваться в других директивах
совместно с результирующей переменной.
Если исходное значение совпадает с именем одного из специальных параметров,
описанных ниже, перед ним следует поставить символ `\`.
В качестве результирующего значения можно указать текст, переменную и их комбинации.
Также поддерживаются следующие специальные параметры:
| `default` значение | задает результирующее значение, если исходное значение не совпадает ни с
одним из перечисленных. Если параметр `default` не указан,
результирующим значением по умолчанию будет пустая строка. |
|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `hostnames` | указывает, что в качестве исходных значений можно использовать маску для
первой или последней части имени хоста. Этот параметр следует указывать
перед списком значений. |
Например,
```nginx
*.example.com 1;
example.* 1;
```
Вместо двух записей
```nginx
example.com 1;
*.example.com 1;
```
можно использовать одну:
```nginx
.example.com 1;
```
| `include` файл | включает файл со значениями. Включений может быть несколько. |
|------------------|----------------------------------------------------------------|
| `volatile` | указывает, что переменная не кэшируется. |
Если исходному значению соответствует несколько из указанных вариантов, например, одновременно подходят и маска, и регулярное выражение, будет выбран первый подходящий вариант в следующем порядке приоритета:
1. Cтроковое значение без маски.
2. Самое длинное строковое значение с маской в начале, например `*.example.com`.
3. Самое длинное строковое значение с маской в конце, например `mail.*`.
4. Первое подходящее регулярное выражение (в порядке следования в конфигурационном файле).
5. Значение по умолчанию (`default`).
### map_hash_bucket_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `map_hash_bucket_size` размер; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `map_hash_bucket_size 32|64|128;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream |
Задает размер корзины в хэш-таблицах для переменных [map](#s-map). Значение по умолчанию зависит от размера строки кэша процессора. Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
### map_hash_max_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `map_hash_max_size` размер; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `map_hash_max_size 2048;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream |
Задает максимальный размер хэш-таблиц для переменных [map](#s-map). Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
# https://angie.software/angie/docs/configuration/modules/stream/stream_mqtt_preread.md
# MQTT Preread
Позволяет извлекать идентификатор клиента и имя пользователя
из пакетов `CONNECT` протокола Message Queuing Telemetry Transport (MQTT)
версий
[3.1.1](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718028)
и
[5.0](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901033).
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild)
модуль необходимо включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-stream_mqtt_preread_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
## Пример конфигурации
### Выбор сервера в группе по идентификатору клиента:
```nginx
stream {
mqtt_preread on;
upstream mqtt {
hash $mqtt_preread_clientid;
# ...
}
}
```
## Директивы
### mqtt_preread
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `mqtt_preread` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `mqtt_preread off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Управляет извлечением информации из пакета `CONNECT`
на этапе
[предварительного чтения](https://angie.software//angie/docs/configuration/processing.md#stream-sessions).
Если параметр включен (`on`),
то в контексте, где он задан,
заполняются перечисленные ниже переменные.
## Встроенные переменные
Подробное описание семантики значений
см. в спецификации протокола MQTT версий
[3.1.1](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718031)
и [5.0](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901033).
### `$mqtt_preread_clientid`
Уникальный идентификатор клиента.
### `$mqtt_preread_username`
Необязательное имя пользователя.
# https://angie.software/angie/docs/configuration/modules/stream/stream_pass.md
# Pass
Позволяет передавать принятое соединение напрямую на любой настроенный слушающий
сокет в модуль [HTTP](https://angie.software//angie/docs/configuration/modules/index.md#modules-http), [потоковый](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream) или [почтовый](https://angie.software//angie/docs/configuration/modules/index.md#modules-mail) модули.
Модуль допускает выборочную SSL-терминацию на основе SNI.
## Пример конфигурации
После того, как модуль `stream` завершит обработку SSL/TLS,
он передает соединение в модуль `http`:
```nginx
stream {
server {
listen 8000 default_server;
ssl_preread on;
# ...
}
server {
listen 8000;
server_name foo.example.com;
pass 127.0.0.1:8001; # to HTTP
}
server {
listen 8000;
server_name bar.example.com;
# ...
}
}
http {
server {
listen 8001 ssl;
# ...
location / {
root html;
}
}
}
```
## Директивы
### pass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `pass` адрес; |
|------------------------------------------------------------------------------------------|-----------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server |
Эта директива задает адрес сервера, на который должно быть передано клиентское
соединение. Адрес можно указать как IP-адрес и порт:
```nginx
pass 127.0.0.1:12345;
```
Или как путь к UNIX-сокету:
```nginx
pass unix:/tmp/stream.socket;
```
Также адрес можно задать с помощью переменных:
```nginx
pass $upstream;
```
# https://angie.software/angie/docs/configuration/modules/stream/stream_proxy.md
# Proxy
Позволяет проксировать потоки данных по TCP, UDP и UNIX-сокетам.
## Пример конфигурации
```nginx
server {
listen 127.0.0.1:12345;
proxy_pass 127.0.0.1:8080;
}
server {
listen 12345;
proxy_connect_timeout 1s;
proxy_timeout 1m;
proxy_pass example.com:12345;
}
server {
listen 53 udp reuseport;
proxy_timeout 20s;
proxy_pass dns.example.com:53;
}
server {
listen [::1]:12345;
proxy_pass unix:/tmp/stream.socket;
}
```
## Директивы
### proxy_bind
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_bind` адрес [`transparent`] | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает локальный IP-адрес, который будет использоваться в исходящих соединениях с проксируемым сервером. В значении параметра допустимо использование переменных. Специальное значение `off` отменяет действие унаследованной с предыдущего уровня конфигурации директивы proxy_bind, позволяя системе самостоятельно выбирать локальный IP-адрес.
Параметр `transparent` позволяет задать нелокальный IP-aдрес, который будет использоваться в исходящих соединениях с проксируемым сервером, например, реальный IP-адрес клиента:
```nginx
proxy_bind $remote_addr transparent;
```
Для работы параметра обычно требуется запустить рабочие процессы Angie с привилегиями [суперпользователя](https://angie.software//angie/docs/configuration/modules/core.md#user). В Linux этого не требуется, так как если указан параметр transparent, то рабочие процессы наследуют capability CAP_NET_RAW из главного процесса.
#### NOTE
Необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с проксируемого сервера.
### proxy_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_buffer_size` размер; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `proxy_buffer_size 16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает размер буфера, в который будут читаться данные, получаемые от проксируемого сервера. Также задает размер буфера, в который будут читаться данные, получаемые от клиента.
### proxy_connect_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_connect_timeout` время; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `proxy_connect_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает таймаут для установления соединения с проксируемым сервером.
### proxy_connection_drop
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_connection_drop` время | `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| По умолчанию | `proxy_connection_drop off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Настраивает завершение всех соединений с проксируемым сервером,
если он был удален из группы или помечен как постоянно недоступный
в результате процесса [reresolve](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve)
или [команды API](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods) `DELETE`.
Сессия завершается, когда обрабатывается следующее событие чтения или записи
для клиента или проксируемого сервера.
Установка времени включает [таймаут](https://angie.software//angie/docs/configuration/configfile.md#syntax) до завершения сессии;
при выборе значения `on` сессии завершаются немедленно.
### proxy_download_rate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_download_rate` скорость; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `proxy_download_rate 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Ограничивает скорость чтения данных от проксируемого сервера;
`скорость` задается в байтах в секунду.
| `0` | отключает ограничение скорости |
|-------|----------------------------------|
#### NOTE
Ограничение устанавливается на соединение, поэтому, если Angie одновременно откроет два соединения к проксируемому серверу, суммарная скорость будет вдвое выше заданного ограничения.
В значении параметра можно использовать переменные. Это может быть полезно в случаях, когда скорость нужно ограничивать в зависимости от какого-либо условия:
```nginx
map $slow $rate {
1 4k;
2 8k;
}
proxy_download_rate $rate
```
### proxy_half_close
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_half_close` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `proxy_half_close off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Разрешает или запрещает независимое закрытие каждой из сторон проксируемого соединения TCP ("TCP half-close"). Если разрешено, то проксирование по TCP будет продолжаться, пока обе стороны не закроют соединение.
### proxy_next_upstream
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_next_upstream` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `proxy_next_upstream on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
При невозможности установить соединение с проксируемым сервером определяет, будет ли клиентское соединение передано [следующему серверу](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream).
Передача соединения следующему серверу может быть ограничена по [количеству попыток](#s-proxy-next-upstream-tries) и по [времени](#s-proxy-next-upstream-timeout).
### proxy_next_upstream_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_next_upstream_timeout` время; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `proxy_next_upstream_timeout 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Ограничивает время, в течение которого возможна передача запроса [следующему](#s-proxy-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### proxy_next_upstream_tries
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_next_upstream_tries` число; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `proxy_next_upstream_tries 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Ограничивает число допустимых попыток для передачи запроса [следующему](#s-proxy-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### proxy_pass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_pass` адрес; |
|------------------------------------------------------------------------------------------|-----------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server |
Задает адрес проксируемого сервера;
`адрес` может быть указан в виде доменного имени или IP-адреса,
за которым следует порт:
```nginx
proxy_pass localhost:12345;
```
или в виде пути UNIX-сокета:
```nginx
proxy_pass unix:/tmp/stream.socket;
```
Если доменному имени соответствует несколько адресов, то все они будут использоваться по очереди (round-robin). Кроме того, в качестве адреса можно указать [группу серверов](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream).
Адрес можно также задать с помощью переменных:
```nginx
proxy_pass $upstream;
```
В этом случае имя сервера ищется среди описанных [групп серверов](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream) и если не найдено, то определяется с помощью [resolver](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-resolver)'а.
### proxy_protocol
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_protocol` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `proxy_protocol off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Включает [протокол PROXY](http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) для соединений с проксируемым сервером.
### proxy_protocol_version
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_protocol_version` `1` | `2`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `proxy_protocol_version 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает версию протокола PROXY, используемую при соединениях с проксируемым сервером. Настройка действует при включенной директиве [proxy_protocol](#s-proxy-protocol). Версия 2 позволяет отправлять TLV, заданные директивой [proxy_protocol_tlv](#s-proxy-protocol-tlv).
### proxy_protocol_tlv
#### Versionadded
Добавлено в версии 1.11.0.
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_protocol_tlv` имя значение; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Добавляет TLV в заголовок протокола PROXY версии 2, отправляемый на проксируемый сервер. Значение может содержать переменные. Имя может быть именем типа TLV или его числовым значением; в последнем случае значение задается в шестнадцатеричном виде и должно начинаться с 0x. Для TLV SSL используйте префикс `ssl_`; специальное имя `ssl_verify` задает поле verify структуры SSL TLV. Директива используется только при значении `2` в [proxy_protocol_version](#s-proxy-protocol-version).
### proxy_requests
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_requests` число; |
|------------------------------------------------------------------------------------------|---------------------------|
| По умолчанию | `proxy_requests 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает число датаграмм, полученных от клиента, по достижении которого удаляется привязка между клиентом и существующей UDP-сессией. После получения указанного количества датаграмм следующая датаграмма, полученная от того же клиента, начинает новую сессию. Сессия завершится после отправки всех принятых датаграмм на проксируемый сервер и получения указанного количества [ответов](#s-proxy-responses) или после [таймаута](#s-proxy-timeout).
### proxy_responses
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_responses` число; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает количество датаграмм, ожидаемых от проксируемого сервера в ответ на датаграмму клиента в случае, если используется протокол [UDP](https://angie.software//angie/docs/configuration/modules/stream/index.md#stream-protocol). Задаваемое число служит подсказкой для завершения сессии. По умолчанию количество датаграмм не ограничено.
Если указано нулевое значение, то ответ не ожидается. Однако если ответ получен и сессия еще не завершилась, то ответ будет обработан.
### proxy_socket_keepalive
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_socket_keepalive` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `proxy_socket_keepalive off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Конфигурирует поведение "TCP keepalive" для исходящих соединений к проксируемому серверу.
| `""` | По умолчанию для сокета действуют настройки операционной системы. |
|--------|---------------------------------------------------------------------|
| `on` | для сокета включается параметр SO_KEEPALIVE |
### proxy_ssl
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `proxy_ssl off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Включает протоколы SSL/TLS для соединений с проксируемым сервером.
### proxy_ssl_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_certificate` файл [файл]; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает файл с сертификатом в формате PEM для аутентификации на проксируемом сервере. В имени файла можно использовать переменные.
При включенном [proxy_ssl_ntls](#s-proxy-ssl-ntls) директива принимает два аргумента вместо одного:
```nginx
server {
proxy_ssl_ntls on;
proxy_ssl_certificate sign.crt enc.crt;
proxy_ssl_certificate_key sign.key enc.key;
proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";
proxy_pass backend:12345;
}
```
### proxy_ssl_certificate_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_certificate_key` файл [файл]; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Вместо `файла` можно указать значение `store:scheme:id`, которое используется для загрузки ключа с указанным id и URI-схемой scheme, зарегистрированной в OpenSSL provider, например [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).
Задает файл с секретным ключом в формате PEM для аутентификации на проксируемом сервере. В имени файла можно использовать переменные.
При включенном [proxy_ssl_ntls](#s-proxy-ssl-ntls) директива принимает два аргумента вместо одного:
```nginx
server {
proxy_ssl_ntls on;
proxy_ssl_certificate sign.crt enc.crt;
proxy_ssl_certificate_key sign.key enc.key;
proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";
proxy_pass backend:12345;
}
```
### proxy_ssl_ciphers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_ciphers` шифры; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `proxy_ssl_ciphers DEFAULT;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Описывает разрешенные шифры для запросов к проксируемому серверу. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL.
Список шифров зависит от установленной версии OpenSSL.
Полный список можно посмотреть с помощью команды `openssl ciphers`.
#### WARNING
Директива `proxy_ssl_ciphers` *не* настраивает шифры для TLS 1.3 при
использовании OpenSSL. Для настройки шифров TLS 1.3 в OpenSSL используйте
директиву [proxy_ssl_conf_command](#s-proxy-ssl-conf-command), добавленную для расширенной
конфигурации SSL.
- В LibreSSL шифры TLS 1.3 *можно* настраивать с помощью
`proxy_ssl_ciphers`.
- В BoringSSL шифры TLS 1.3 настроить невозможно.
### proxy_ssl_conf_command
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_conf_command` имя значение; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает произвольные конфигурационные [команды](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) OpenSSL при установлении соединения с проксируемым сервером.
#### NOTE
Директива поддерживается при использовании OpenSSL 1.0.2 и выше.
Чтобы настроить шифры TLS 1.3 в OpenSSL, используйте команду `ciphersuites`.
На одном уровне может быть указано несколько директив proxy_ssl_conf_command. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы proxy_ssl_conf_command.
#### WARNING
Следует учитывать, что изменение настроек OpenSSL напрямую может привести к неожиданному поведению.
### proxy_ssl_crl
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_crl` файл; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Указывает файл с отозванными сертификатами (CRL) в формате PEM, используемыми при [проверке](#s-proxy-ssl-verify) сертификата проксируемого сервера.
### proxy_ssl_name
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_name` имя; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `proxy_ssl_name` хост из `proxy_pass;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Позволяет переопределить имя сервера, используемое при [проверке](#s-proxy-ssl-verify) сертификата проксируемого сервера, а также для [передачи его через SNI](#s-proxy-ssl-server-name) при установлении соединения с проксируемым сервером. Имя сервера можно также задать с помощью переменных.
По умолчанию используется имя хоста из адреса, заданного директивой [proxy_pass](#s-proxy-pass).
### proxy_ssl_ntls
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_ntls` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `proxy_ssl_ntls off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Включает клиентскую поддержку NTLS при использовании TLS библиотеки [TongSuo](https://github.com/Tongsuo-Project/Tongsuo).
```nginx
server {
proxy_ssl_ntls on;
proxy_ssl_certificate sign.crt enc.crt;
proxy_ssl_certificate_key sign.key enc.key;
proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";
proxy_pass backend:12345;
}
```
#### NOTE
Angie необходимо собрать с использованием параметра конфигурации `--with-ntls`, с соответствующей SSL библиотекой с поддержкой NTLS
```default
./configure --with-openssl=../Tongsuo-8.3.0 \
--with-openssl-opt=enable-ntls \
--with-ntls
```
### proxy_ssl_password_file
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_password_file` файл; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает файл с паролями от [секретных ключей](#s-proxy-ssl-certificate-key), где каждый пароль указан на отдельной строке. Пароли применяются по очереди в момент загрузки ключа.
### proxy_ssl_protocols
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`]; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| По умолчанию | `proxy_ssl_protocols TLSv1.2 TLSv1.3;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Разрешает указанные протоколы для соединений с проксируемым сервером.
### proxy_ssl_server_name
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_server_name` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `proxy_ssl_server_name off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Разрешает или запрещает передачу имени сервера,
заданного директивой [proxy_ssl_name](#s-proxy-ssl-name),
через расширение
[Server Name Indication](http://en.wikipedia.org/wiki/Server_Name_Indication)
протокола TLS
(SNI,
[RFC 6066](https://datatracker.ietf.org/doc/html/rfc6066.html))
при установлении соединения с проксируемым сервером.
### proxy_ssl_session_reuse
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_session_reuse` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| По умолчанию | `proxy_ssl_session_reuse on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Определяет, использовать ли повторно SSL-сессии при работе с проксируемым сервером. Если в логах появляются ошибки "SSL3_GET_FINISHED:digest check failed", то можно попробовать выключить повторное использование сессий.
### proxy_ssl_trusted_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_trusted_certificate` файл; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает файл с доверенными сертификатами CA в формате PEM, используемыми при [проверке](#s-proxy-ssl-verify) сертификата проксируемого HTTPS-сервера.
### proxy_ssl_verify
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_verify` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `proxy_ssl_verify off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Разрешает или запрещает проверку сертификата проксируемого сервера.
### proxy_ssl_verify_depth
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_verify_depth` число; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `proxy_ssl_verify_depth 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Устанавливает глубину проверки в цепочке сертификатов проксируемого сервера.
### proxy_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_timeout` время; |
|------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию | `proxy_timeout 10m;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает таймаут между двумя идущими подряд операциями чтения или записи на клиентском соединении или соединении с проксируемым сервером. Если по истечении этого времени данные не передавались, соединение закрывается.
### proxy_upload_rate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_upload_rate` скорость; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `proxy_upload_rate 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Ограничивает скорость чтения данных от клиента. Скорость задается в байтах в секунду.
| `0` | отключает ограничение скорости |
|-------|----------------------------------|
#### NOTE
Ограничение устанавливается на соединение, поэтому, если клиент одновременно откроет два соединения, суммарная скорость будет вдвое выше заданного ограничения.
В значении параметра можно использовать переменные. Это может быть полезно в случаях, когда скорость нужно ограничивать в зависимости от какого-либо условия:
```nginx
map $slow $rate {
1 4k;
2 8k;
}
proxy_upload_rate $rate;
```
# https://angie.software/angie/docs/configuration/modules/stream/stream_rdp_preread.md
# RDP Preread
При использовании протокола RDP позволяет извлекать cookie,
которые используются для идентификации и управления сессиями,
до момента принятия решения о балансировке.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild)
модуль необходимо включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑stream_rdp_preread_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
## Пример конфигурации
### Привязка к выдавшему cookie серверу
Конфигурация использует режим `learn` директивы [sticky](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky):
```nginx
stream {
rdp_preread on;
upstream rdp {
server 127.0.0.1:3390 sid=a;
server 127.0.0.1:3391 sid=b;
sticky learn lookup=$rdp_cookie create=$rdp_cookie zone=sessions:1m;
}
}
```
## Директивы
### rdp_preread
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `rdp_preread` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `rdp_preread off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Управляет извлечением информации из cookie протокола RDP
на этапе
[предварительного чтения](https://angie.software//angie/docs/configuration/processing.md#stream-sessions).
Если параметр включен (`on`),
то в контексте, где он задан,
заполняются перечисленные ниже переменные.
## Встроенные переменные
Семантика значений в составе cookie зависит от версии протокола RDP.
### `$rdp_cookie`
Значение cookie целиком.
### `$rdp_cookie_<имя>`
Значение поля cookie с заданным именем.
# https://angie.software/angie/docs/configuration/modules/stream/stream_realip.md
# RealIP
Позволяет менять адрес и порт клиента на переданные в заголовке протокола PROXY. Протокол PROXY должен быть предварительно включен при помощи установки параметра `proxy_protocol` в директиве [listen](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-listen).
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑stream_realip_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
## Пример конфигурации
```nginx
listen 12345 proxy_protocol;
set_real_ip_from 192.168.1.0/24;
set_real_ip_from 192.168.2.1;
set_real_ip_from 2001:0db8::/32;
```
## Директивы
### set_real_ip_from
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `set_real_ip_from` адрес | CIDR | `unix:`; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает доверенные адреса, которые передают верный адрес для замены. Если указано специальное значение `unix:`, доверенными будут считаться все UNIX-сокеты.
## Встроенные переменные
### `$realip_remote_addr`
хранит исходный адрес клиента
### `$realip_remote_port`
хранит исходный порт клиента
# https://angie.software/angie/docs/configuration/modules/stream/stream_return.md
# Return
Позволяет отправить заданное значение клиенту и после этого закрыть соединение.
## Пример конфигурации
```nginx
server {
listen 12345;
return $time_iso8601;
}
```
## Директивы
### return
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `return` значение; |
|------------------------------------------------------------------------------------------|----------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server |
Задает значение, отправляемое клиенту. В качестве значения можно использовать текст, переменные и их комбинации.
# https://angie.software/angie/docs/configuration/modules/stream/stream_set.md
# Set
Позволяет устанавливать значение переменной.
## Пример конфигурации
```nginx
server {
listen 12345;
set $true 1;
}
```
## Директивы
### set
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `set` $переменная значение; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server |
Устанавливает значение указанной переменной. В качестве значения можно использовать текст, переменные и их комбинации.
# https://angie.software/angie/docs/configuration/modules/stream/stream_split_clients.md
# Split Clients
Модуль генерирует переменные для A/B-тестирования, канареечных релизов
и других сценариев, которые направляют определенный процент клиентов на один
сервер или конфигурацию, а остальных — куда-то еще.
## Пример конфигурации
```nginx
stream {
# ...
split_clients "${remote_addr}AAA" $upstream {
0.5% feature_test1;
2.0% feature_test2;
* production;
}
server {
# ...
proxy_pass $upstream;
}
}
```
## Директивы
### split_clients
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `split_clients` строка $переменная { ... } |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream |
Создает $переменную, хэшируя строку;
переменные в строке подставляются,
результат хэшируется,
затем по значению хэша выбирается строковое значение $переменной.
Функция хэширования использует
[MurmurHash2](https://en.wikipedia.org/wiki/MurmurHash#MurmurHash2)
(32 бит),
и весь диапазон ее значений
(с 0 по 4294967295)
сопоставляется с корзинами в порядке появления;
процентные величины определяют размер корзин.
В конце может стоять метасимвол (`*`);
хэши, не попавшие в другие корзины, сопоставляются с приданным ему значением.
Пример:
```nginx
split_clients "${remote_addr}AAA" $variant {
0.5% .one;
2.0% .two;
* "";
}
```
Здесь после подстановки в строке `$*remote_addr*AAA`
значения хэша распределяются следующим образом:
- значения от 0 до 21474835 (0,5%) дают `.one`;
- значения от 21474836 до 107374180 (2%) дают `.two`;
- значения от 107374181 до 4294967295 (все остальные) дают `""`
(пустую строку).
# https://angie.software/angie/docs/configuration/modules/stream/stream_ssl.md
# SSL
Обеспечивает необходимую поддержку для работы прокси-сервера по протоколу SSL/TLS.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑stream_ssl_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
#### NOTE
Для этого модуля нужна библиотека OpenSSL.
## Пример конфигурации
Для уменьшения загрузки процессора рекомендуется
* установить число [рабочих процессов](https://angie.software//angie/docs/configuration/modules/core.md#worker-processes) равным числу процессоров,
* включить [разделяемый кэш](#s-ssl-session-cache) сессий,
* выключить [встроенный кэш](#s-ssl-session-cache) сессий
* и, возможно, увеличить [время жизни](#s-ssl-session-timeout) сессии (по умолчанию 5 минут):
```nginx
worker_processes auto;
stream {
#...
server {
listen 12345 ssl;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
ssl_certificate /usr/local/angie/conf/cert.pem;
ssl_certificate_key /usr/local/angie/conf/cert.key;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
# ...
}
```
## Директивы
### ssl_alpn
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_alpn` протокол ...; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает список поддерживаемых протоколов [ALPN](https://datatracker.ietf.org/doc/html/rfc7301). Один из протоколов должен быть [согласован](#v-s-ssl-alpn-protocol), если клиент использует ALPN:
```nginx
map $ssl_alpn_protocol $proxy {
h2 127.0.0.1:8001;
http/1.1 127.0.0.1:8002;
}
server {
listen 12346;
proxy_pass $proxy;
ssl_alpn h2 http/1.1;
}
```
### ssl_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_certificate` файл; |
|------------------------------------------------------------------------------------------|---------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Указывает файл с сертификатом в формате PEM для данного сервера. Если вместе с основным сертификатом нужно указать промежуточные, то они должны находиться в этом же файле в следующем порядке — сначала основной сертификат, а затем промежуточные. В этом же файле может находиться секретный ключ в формате PEM.
Директива может быть указана несколько раз для загрузки сертификатов разных типов, например RSA и ECDSA:
```nginx
server {
listen 12345 ssl;
ssl_certificate example.com.rsa.crt;
ssl_certificate_key example.com.rsa.key;
ssl_certificate example.com.ecdsa.crt;
ssl_certificate_key example.com.ecdsa.key;
# ...
}
```
Возможность задавать отдельные цепочки сертификатов для разных сертификатов есть только в OpenSSL 1.0.2 и выше. Для более старых версий следует указывать только одну цепочку сертификатов.
#### NOTE
В имени файла можно использовать переменные при использовании OpenSSL 1.0.2 и выше:
```nginx
ssl_certificate $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;
```
При использовании переменных сертификат загружается при каждой операции SSL-рукопожатия, что может отрицательно влиять на производительность.
Вместо `файла` можно указать значение "data:$переменная", при котором
сертификат загружается из переменной без использования промежуточных файлов.
Ненадлежащее использование подобного синтаксиса может быть небезопасно, например данные секретного ключа могут попасть в [лог ошибок](https://angie.software//angie/docs/configuration/modules/core.md#error-log).
### ssl_certificate_compression
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_certificate_compression` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| По умолчанию | `ssl_certificate_compression off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Разрешает сжатие TLS 1.3 [сертификатов сервера](https://datatracker.ietf.org/doc/html/rfc8879).
#### NOTE
Директива поддерживается при использовании OpenSSL версии 3.2 и выше; список поддерживаемых алгоритмов сжатия предоставляется библиотекой.
#### NOTE
Директива поддерживается при использовании [BoringSSL](https://boringssl.googlesource.com/boringssl/); список поддерживаемых алгоритмов сжатия включает `zlib`.
Если включен [ssl_stapling](#s-ssl-stapling), сжатие сертификатов отключается.
### ssl_certificate_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_certificate_key` файл; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Указывает файл с секретным ключом в формате PEM для данного виртуального сервера.
#### NOTE
В имени файла можно использовать переменные при использовании OpenSSL 1.0.2 и выше.
Вместо `файла` можно указать значение "engine:имя:id", которое загружает
ключ с указанным id из OpenSSL engine с заданным именем.
Вместо `файла` можно указать значение "store:scheme:id", которое
используется для загрузки ключа с указанным id и URI-схемой scheme,
зарегистрированной в OpenSSL provider, например [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).
Вместо `файла` также можно указать значение "data:$переменная", при
котором секретный ключ загружается из переменной без использования промежуточных
файлов. При этом следует учитывать, что ненадлежащее использование подобного
синтаксиса может быть небезопасно, например данные секретного ключа могут
попасть в [лог ошибок](https://angie.software//angie/docs/configuration/modules/core.md#error-log).
### ssl_ciphers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ciphers` шифры; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `ssl_ciphers HIGH:!aNULL:!MD5;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Описывает разрешенные шифры. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL, например:
```nginx
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
```
Список шифров зависит от установленной версии OpenSSL.
Полный список можно посмотреть с помощью команды `openssl ciphers`.
#### WARNING
Директива `ssl_ciphers` *не* настраивает шифры для TLS 1.3 при
использовании OpenSSL. Для настройки шифров TLS 1.3 в OpenSSL используйте
директиву [ssl_conf_command](#s-ssl-conf-command), добавленную для расширенной
конфигурации SSL.
- В LibreSSL шифры TLS 1.3 *можно* настраивать с помощью
`ssl_ciphers`.
- В BoringSSL шифры TLS 1.3 настроить невозможно.
### ssl_client_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_client_certificate` файл; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает файл с доверенными сертификатами CA в формате PEM, которые используются
для [проверки](#s-ssl-verify-client) клиентских сертификатов и ответов
OCSP, если включен [ssl_stapling](#s-ssl-stapling).
Список сертификатов будет отправляться клиентам. Если это нежелательно, можно воспользоваться директивой [ssl_trusted_certificate](#s-ssl-trusted-certificate).
### ssl_conf_command
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_conf_command` имя значение; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает произвольные [конфигурационные команды](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) OpenSSL.
#### NOTE
Директива поддерживается при использовании OpenSSL 1.0.2 и выше.
Чтобы настроить шифры TLS 1.3 в OpenSSL, используйте команду `ciphersuites`.
На одном уровне может быть указано несколько директив ssl_conf_command:
```nginx
ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;
```
Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы ssl_conf_command.
#### WARNING
Изменение настроек OpenSSL напрямую может привести к неожиданному поведению.
### ssl_crl
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_crl` файл; |
|------------------------------------------------------------------------------------------|-------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Указывает файл с отозванными сертификатами (CRL) в формате PEM, используемыми для [проверки](#s-ssl-verify-client) клиентских сертификатов.
### ssl_dhparam
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_dhparam` файл; |
|------------------------------------------------------------------------------------------|-----------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Указывает файл с параметрами для DHE-шифров.
#### WARNING
По умолчанию параметры не заданы, и соответственно DHE-шифры не будут использоваться.
### ssl_early_data
#### Versionadded
Добавлено в версии 1.9.0.
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_early_data` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `ssl_early_data off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Разрешает или запрещает TLS 1.3 [early data](https://datatracker.ietf.org/doc/html/rfc8446#section-2.3).
#### NOTE
Директива поддерживается при использовании OpenSSL 1.1.1 и выше или [BoringSSL](https://boringssl.googlesource.com/boringssl/).
### ssl_encrypted_hello_key
#### Versionadded
Добавлено в версии 1.11.0.
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_encrypted_hello_key` файл; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Указывает файл с приватным ключом ECH и списком ECHConfigList в формате PEM.
Директива может быть указана несколько раз.
Требуется сборка OpenSSL или BoringSSL с поддержкой Encrypted Client Hello (ECH),
иначе директива не поддерживается.
### ssl_ecdh_curve
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ecdh_curve` кривая; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `ssl_ecdh_curve auto;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает кривую для ECDHE-шифров.
#### NOTE
При использовании OpenSSL 1.0.2 и выше можно указывать несколько кривых, например:
```nginx
ssl_ecdh_curve prime256v1:secp384r1;
```
Специальное значение `auto` соответствует встроенному в библиотеку OpenSSL списку кривых для OpenSSL 1.0.2 и выше, или prime256v1 для более старых версий.
#### NOTE
При использовании OpenSSL 1.0.2 и выше директива задает список кривых, поддерживаемых сервером. Поэтому для работы ECDSA-сертификатов важно, чтобы список включал кривые, используемые в сертификатах.
### ssl_handshake_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_handshake_timeout` время; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `ssl_handshake_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает таймаут для завершения операции SSL-рукопожатия.
### ssl_ocsp
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ocsp` `on` | `off` | `leaf`; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `ssl_ocsp off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Включает проверку OCSP для цепочки клиентских сертификатов. Параметр
`leaf` включает проверку только клиентского сертификата.
Для работы проверки OCSP необходимо дополнительно установить значение директивы
[ssl_verify_client](#s-ssl-verify-client) в `on` или `optional`.
Для преобразования имени хоста OCSP-респондера в адрес необходимо дополнительно
задать директиву [resolver](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-resolver).
Пример:
```nginx
ssl_verify_client on;
ssl_ocsp on;
resolver 127.0.0.53;
```
### ssl_ocsp_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ocsp_cache` `off` | [shared:имя:размер]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| По умолчанию | `ssl_ocsp_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает имя и размер кэша, который хранит статус клиентских сертификатов для
проверки OCSP-ответов. Кэш разделяется между всеми рабочими процессами. Кэш с
одинаковым названием может использоваться в нескольких виртуальных серверах.
Параметр `off` запрещает использование кэша.
### ssl_ocsp_responder
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ocsp_responder` uri; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Переопределяет URI OCSP-респондера, указанный в расширении сертификата
["Authority Information Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1) для
[проверки](#s-ssl-ocsp) клиентских сертификатов.
Поддерживаются только OCSP-респондеры на основе `http://`:
```nginx
ssl_ocsp_responder http://ocsp.example.com/;
```
### ssl_ntls
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ntls` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `ssl_ntls off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Включает серверную поддержку NTLS при использовании TLS библиотеки [TongSuo](https://github.com/Tongsuo-Project/Tongsuo)
```nginx
listen ... ssl;
ssl_ntls on;
```
#### NOTE
Angie необходимо собрать с использованием параметра конфигурации `--with-ntls`, с соответствующей SSL библиотекой с поддержкой NTLS
```default
./configure --with-openssl=../Tongsuo-8.3.0 \
--with-openssl-opt=enable-ntls \
--with-ntls
```
### ssl_password_file
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_password_file` файл; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает файл с паролями от [секретных ключей](#s-ssl-certificate-key), где каждый пароль указан на отдельной строке. Пароли применяются по очереди в момент загрузки ключа.
Пример:
```nginx
stream {
ssl_password_file /etc/keys/global.pass;
...
server {
listen 127.0.0.1:12345;
ssl_certificate_key /etc/keys/first.key;
}
server {
listen 127.0.0.1:12346;
# вместо файла можно указать именованный канал
ssl_password_file /etc/keys/fifo;
ssl_certificate_key /etc/keys/second.key;
}
}
```
### ssl_prefer_server_ciphers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_prefer_server_ciphers` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | `ssl_prefer_server_ciphers off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
При использовании протоколов SSLv3 и TLS устанавливает приоритет серверных шифров над клиентскими.
### ssl_protocols
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`]; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| По умолчанию | `ssl_protocols TLSv1.2 TLSv1.3;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Разрешает указанные протоколы.
#### NOTE
Параметры TLSv1.1 и TLSv1.2 работают только при использовании OpenSSL 1.0.1 и выше.
Параметр TLSv1.3 работает только при использовании OpenSSL 1.1.1 и выше.
### ssl_session_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_cache` `off` | `none` | [builtin[:размер]] [shared:название:размер]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| По умолчанию | `ssl_session_cache none;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает тип и размеры кэшей для хранения параметров сессий. Тип кэша может быть следующим:
| `off` | жесткое запрещение использования кэша сессий: Angie явно сообщает клиенту, что сессии не могут использоваться повторно. |
|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `none` | мягкое запрещение использования кэша сессий: Angie сообщает клиенту, что сессии могут использоваться повторно, но на самом деле не хранит параметры сессии в кэше. |
| `builtin` | встроенный в OpenSSL кэш, используется в рамках только одного рабочего процесса. Размер кэша задается в сессиях. Если размер не задан, то он равен 20480 сессиям. Использование встроенного кэша может вести к фрагментации памяти. |
| `shared` | кэш, разделяемый между всеми рабочими процессами. Размер кэша задается в байтах, в 1 мегабайт может поместиться около 4000 сессий. У каждого разделяемого кэша должно быть произвольное название. Кэш с одинаковым названием может использоваться в нескольких серверах. Также он используется для автоматического создания, хранения и периодического обновления ключей сессионных билетов TLS, если они не указаны явно с помощью директивы [ssl_session_ticket_key](#s-ssl-session-ticket-key). |
Можно использовать одновременно оба типа кэша, например:
```nginx
ssl_session_cache builtin:1000 shared:SSL:10m;
```
однако использование только разделяемого кэша без встроенного должно быть более эффективным.
### ssl_session_ticket_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_ticket_key` файл; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает файл с секретным ключом, применяемым при шифровании и расшифровке сессионных билетов TLS. Директива необходима, если один и тот же ключ нужно использовать на нескольких серверах. По умолчанию используется случайно сгенерированный ключ.
Если указано несколько ключей, то только первый ключ используется для шифрования сессионных билетов TLS. Это позволяет настроить ротацию ключей, например:
```nginx
ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;
```
Файл должен содержать 80 или 48 байт случайных данных и может быть создан следующей командой:
```console
openssl rand 80 > ticket.key
```
В зависимости от размера файла для шифрования будет использоваться либо AES256 (для 80-байтных ключей), либо AES128 (для 48-байтных ключей).
### ssl_session_tickets
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_tickets` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `ssl_session_tickets on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Разрешает или запрещает возобновление сессий при помощи [сессионных билетов TLS](https://datatracker.ietf.org/doc/html/rfc5077).
### ssl_session_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_timeout` время; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `ssl_session_timeout 5m;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает время, в течение которого клиент может повторно использовать параметры сессии.
### ssl_stapling
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_stapling` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `ssl_stapling off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает или запрещает [прикрепление OCSP-ответов](https://datatracker.ietf.org/doc/html/rfc6066#section-8) сервером. Пример:
```nginx
ssl_stapling on;
resolver 127.0.0.53;
```
Для работы OCSP-прикрепления должен быть известен сертификат издателя
сертификата сервера. Если в заданном директивой [ssl_certificate](#s-ssl-certificate) файле не
содержится промежуточных сертификатов, то сертификат издателя сертификата
сервера следует поместить в файл, заданный директивой
[ssl_trusted_certificate](#s-ssl-trusted-certificate).
#### WARNING
Для преобразования имени хоста OCSP-респондера в адрес необходимо
дополнительно задать директиву [resolver](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-resolver).
### ssl_stapling_file
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_stapling_file` файл; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Если значение задано, то вместо опроса OCSP-респондера, указанного в сертификате
сервера, ответ берется из указанного файла.
Ответ должен быть в формате DER и может быть сгенерирован командой
`openssl ocsp`.
### ssl_stapling_responder
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_stapling_responder` `uri`; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Переопределяет URI OCSP-респондера, указанный в расширении сертификата
["Authority Information Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1).
Поддерживаются только OCSP-респондеры на основе `http://`:
```nginx
ssl_stapling_responder http://ocsp.example.com/;
```
### ssl_stapling_verify
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_stapling_verify` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `ssl_stapling_verify off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает или запрещает проверку ответов OCSP сервером.
Для работоспособности проверки сертификат издателя сертификата сервера, корневой
сертификат и все промежуточные сертификаты должны быть указаны как доверенные с
помощью директивы [ssl_trusted_certificate](#s-ssl-trusted-certificate).
### ssl_trusted_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_trusted_certificate` файл; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Задает файл с доверенными сертификатами CA в формате PEM, которые используются для [проверки](#s-ssl-verify-client) клиентских сертификатов.
В отличие от [ssl_client_certificate](#s-ssl-client-certificate), список этих сертификатов не будет отправляться клиентам.
### ssl_verify_client
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_verify_client` `on` | `off` | `optional` | `optional_no_ca`; |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| По умолчанию | `ssl_verify_client off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Разрешает проверку клиентских сертификатов. Результат проверки доступен через переменную [$ssl_client_verify](#v-s-ssl-client-verify). Если при проверке клиентского сертификата произошла ошибка или клиент не предоставил требуемый сертификат, соединение закрывается.
| `optional` | запрашивает клиентский сертификат, и если сертификат был предоставлен, проверяет его |
|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `optional_no_ca` | запрашивает сертификат клиента, но не требует, чтобы он был подписан доверенным сертификатом CA. Это предназначено для случаев, когда фактическая проверка сертификата осуществляется внешним по отношению к Angie сервисом. |
### ssl_verify_depth
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_verify_depth` число; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `ssl_verify_depth 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Устанавливает глубину проверки в цепочке клиентских сертификатов.
## Встроенные переменные
Модуль stream_ssl поддерживает встроенные переменные:
### `$ssl_alpn_protocol`
возвращает протокол, выбранный при помощи ALPN во время SSL-рукопожатия, либо пустую строку.
### `$ssl_cipher`
возвращает название используемого шифра для установленного SSL-соединения.
### `$ssl_ciphers`
возвращает список шифров, поддерживаемых клиентом. Известные шифры указаны по имени, неизвестные указаны в шестнадцатеричном виде, например:
> AES128-SHA:AES256-SHA:0x00ff
#### NOTE
Переменная полностью поддерживается при использовании OpenSSL версии 1.0.2 и выше. При использовании более старых версий переменная доступна только для новых сессий и может содержать только известные шифры.
### `$ssl_client_cert`
возвращает клиентский сертификат для установленного SSL-соединения в формате PEM перед каждой строкой которого, кроме первой, вставляется символ табуляции.
### `$ssl_client_fingerprint`
возвращает SHA1-отпечаток клиентского сертификата для установленного SSL-соединения.
### `$ssl_client_i_dn`
возвращает строку "issuer DN" клиентского сертификата для установленного SSL-соединения согласно [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253).
### `$ssl_client_raw_cert`
возвращает клиентский сертификат для установленного SSL-соединения в формате PEM.
### `$ssl_client_s_dn`
возвращает строку "subject DN" клиентского сертификата для установленного SSL-соединения согласно [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253).
### `$ssl_client_serial`
возвращает серийный номер клиентского сертификата для установленного SSL-соединения.
### `$ssl_client_sigalg`
возвращает [алгоритм подписи](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) для сертификата клиента в установленном SSL-соединении.
#### NOTE
Переменная поддерживается только при использовании OpenSSL версии 3.5 и выше. При использовании более старых версий значением переменной будет пустая строка.
#### NOTE
Переменная доступна только для новых сессий.
### `$ssl_client_v_end`
возвращает дату окончания срока действия клиентского сертификата.
### `$ssl_client_v_remain`
возвращает число дней, оставшихся до истечения срока действия клиентского сертификата.
### `$ssl_client_v_start`
возвращает дату начала срока действия клиентского сертификата.
### `$ssl_client_verify`
возвращает результат проверки клиентского сертификата: `SUCCESS`, `FAILED:reason` и, если сертификат не был предоставлен, `NONE`.
### `$ssl_curve`
возвращает согласованную кривую, использованную для обмена ключами во время SSL-рукопожатия. Известные кривые указаны по имени, неизвестные указаны в шестнадцатеричном виде, например:
> prime256v1
#### NOTE
Переменная поддерживается при использовании OpenSSL версии 3.0 и выше. При использовании более старых версий значением переменной будет пустая строка.
### `$ssl_curves`
возвращает список кривых, поддерживаемых клиентом. Известные кривые указаны по имени, неизвестные указаны в шестнадцатеричном виде, например:
> 0x001d:prime256v1:secp521r1:secp384r1
#### NOTE
Переменная поддерживается при использовании OpenSSL версии 1.0.2 и выше. При использовании более старых версий значением переменной будет пустая строка.
Переменная доступна только для новых сессий.
### `$ssl_early_data`
возвращает `1`, если используется TLS 1.3 [early data](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-early-data) и операция SSL-рукопожатия не завершена, иначе "".
### `$ssl_encrypted_hello`
#### Versionadded
Добавлено в версии 1.11.0.
возвращает `1`, если используется Encrypted Client Hello (ECH), иначе "".
### `$ssl_protocol`
возвращает протокол установленного SSL-соединения.
### `$ssl_server_cert_type`
принимает значения `RSA`, `DSA`, `ECDSA`, `ED448`,
`ED25519`, `SM2`, `RSA-PSS` или `unknown` в зависимости
от типа сертификата и ключа сервера.
### `$ssl_server_name`
возвращает имя сервера, запрошенное через [SNI](http://en.wikipedia.org/wiki/Server_Name_Indication).
### `$ssl_session_id`
возвращает идентификатор сессии установленного SSL-соединения.
### `$ssl_session_reused`
возвращает `r`, если сессия была использована повторно, иначе ".".
### `$ssl_sigalg`
возвращает [алгоритм подписи](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) для сертификата сервера в установленном SSL-соединении.
#### NOTE
Переменная поддерживается только при использовании OpenSSL версии 3.5 и выше. При использовании более старых версий значением переменной будет пустая строка.
#### NOTE
Переменная доступна только для новых сессий.
# https://angie.software/angie/docs/configuration/modules/stream/stream_ssl_preread.md
# SSL Preread
Позволяет извлекать информацию из сообщения
[ClientHello](https://datatracker.ietf.org/doc/html/rfc5246#section-7.4.1.2)
без терминации TLS,
например имя сервера, запрошенное через
[SNI](https://datatracker.ietf.org/doc/html/rfc6066#section-3),
или протоколы, указанные в
[ALPN](https://datatracker.ietf.org/doc/html/rfc7301).
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑stream_ssl_preread_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
## Пример конфигурации
### Выбор апстрима по имени сервера
```nginx
map $ssl_preread_server_name $name {
backend.example.com backend;
default backend2;
}
upstream backend {
server 192.168.0.1:12345;
server 192.168.0.2:12345;
}
upstream backend2 {
server 192.168.0.3:12345;
server 192.168.0.4:12345;
}
server {
listen 12346;
proxy_pass $name;
ssl_preread on;
}
```
### Выбор сервера по протоколу
```nginx
map $ssl_preread_alpn_protocols $proxy {
~\bh2\b 127.0.0.1:8001;
~\bhttp/1.1\b 127.0.0.1:8002;
~\bxmpp-client\b 127.0.0.1:8003;
}
server {
listen 9000;
proxy_pass $proxy;
ssl_preread on;
}
```
### Выбор сервера по версии протокола SSL
```nginx
map $ssl_preread_protocol $upstream {
"" ssh.example.com:22;
"TLSv1.2" new.example.com:443;
default tls.example.com:443;
}
# ssh и https на одном порту
server {
listen 192.168.0.1:443;
proxy_pass $upstream;
ssl_preread on;
}
```
## Директивы
### ssl_preread
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_preread` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `ssl_preread off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream, server |
Разрешает извлекать информацию из сообщения ClientHello на этапе
[предварительного чтения](https://angie.software//angie/docs/configuration/processing.md#stream-sessions).
## Встроенные переменные
### `$ssl_preread_protocol`
Максимальная версия протокола SSL, поддерживаемая клиентом.
### `$ssl_preread_server_name`
Имя сервера, запрошенное через SNI.
### `$ssl_preread_alpn_protocols`
Список протоколов, переданный клиентом через ALPN.
Значения разделяются запятыми.
# https://angie.software/angie/docs/configuration/modules/stream/stream_upstream.md
# Upstream
Предоставляет контекст для описания группы серверов, которые могут использоваться в директиве [proxy_pass](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-pass).
## Пример конфигурации
```nginx
upstream backend {
hash $remote_addr consistent;
zone backend 1m;
server backend1.example.com:1935 weight=5;
server unix:/tmp/backend3;
server backend3.example.com service=_example._tcp resolve;
server backup1.example.com:1935 backup;
server backup2.example.com:1935 backup;
}
resolver 127.0.0.53 status_zone=resolver;
server {
listen 1936;
proxy_pass backend;
}
```
## Директивы
### upstream
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `upstream` имя { ... } |
|------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | stream |
Описывает группу серверов. Серверы могут слушать на разных портах. Кроме того, можно одновременно использовать серверы, слушающие на TCP- и UNIX-сокетах.
Пример:
```nginx
upstream backend {
zone backend 1m;
server backend1.example.com:1935 weight=5;
server 127.0.0.1:1935 max_fails=3 fail_timeout=30s;
server unix:/tmp/backend2;
server backend3.example.com:1935 resolve;
server backup1.example.com:1935 backup;
}
```
По умолчанию соединения распределяются по серверам циклически (в режиме round-robin) с учетом весов серверов. В вышеприведенном примере каждые 7 соединений будут распределены так: 5 соединений на backend1.example.com:1935 и по одному соединению на второй и третий серверы. Распределение является *равномерным*: соединения к серверу с большим весом распределяются по всему циклу, а не отправляются подряд одной группой.
Если при попытке работы с сервером происходит ошибка, то соединение передается следующему серверу, и так далее до тех пор, пока не будут опробованы все работающие серверы. Если связь с серверами не удалась, соединение будет закрыто.
#### NOTE
По умолчанию сервер, у которого изредка происходят неудачные попытки,
не достигающие порога [max_fails](#s-max-fails),
временно получает меньшую долю соединений
и восстанавливает свою полную долю в течение последующих соединений.
Это отличается от [slow_start](#s-slow-start),
который плавно возвращает сервер к работе только после того,
как сервер был помечен недоступным и затем восстановился.
### server
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `server` адрес [параметры]; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | upstream |
Задает адрес и другие параметры сервера. Адрес может быть указан в виде доменного имени или IP-адреса, и обязательного порта, или в виде пути UNIX-сокета, который указывается после префикса `unix:`. Доменное имя, которому соответствует несколько IP-адресов, задает сразу несколько серверов.
Могут быть заданы следующие параметры:
| `weight=`число | Задает вес сервера. По умолчанию — 1. |
|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `max_conns=`число | Ограничивает максимальное число одновременных активных соединений к проксируемому серверу. Значение по умолчанию равно `0` и означает, что ограничения нет. Если группа не находится в [зоне](#s-u-zone) разделяемой памяти, то ограничение работает отдельно для каждого рабочего процесса. |
`max_fails=`число — задает число неудачных попыток связи с сервером,
которые должны произойти в течение заданного [fail_timeout](#s-fail-timeout) времени для того, чтобы сервер считался недоступным; после
этого он будет повторно проверен через то же самое время.
В данном случае неудачной попыткой считается ошибка или таймаут при установке
соединения с сервером.
#### NOTE
Если директива `server` в группе разрешается в несколько серверов,
ее настройка `max_fails` применяется к каждому серверу отдельно.
Если после разрешения всех директив `server`
в апстриме остается только один сервер,
настройка `max_fails` не действует и будет проигнорирована.
| `max_fails=1` | Число попыток по умолчанию. |
|-----------------|-------------------------------|
| `max_fails=0` | Отключает учет попыток. |
`fail_timeout=`время — задает период времени, в течение которого
должно произойти определенное число неудачных попыток связи с сервером
([max_fails](#s-max-fails)), чтобы сервер считался недоступным.
Затем сервер остается недоступным в течение того же самого времени,
прежде чем будет проверен повторно.
Значение по умолчанию — 10 секунд.
#### NOTE
Если директива `server` в группе разрешается в несколько серверов,
ее настройка `fail_timeout` применяется к каждому серверу отдельно.
Если после разрешения всех директив `server`
в апстриме остается только один сервер,
настройка `fail_timeout` не действует и будет проигнорирована.
| `backup` | Помечает сервер как запасной. На него будут передаваться запросы в случае, если не работают основные серверы. |
|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `down` | Помечает сервер как постоянно недоступный. |
| `drain` (PRO) | Помечает сервер как разгружаемый (draining); это значит,
что он получает только запросы сессий,
привязанных ранее через [sticky](#s-u-sticky).
В остальном поведение такое же, как в режиме `down`. |
#### WARNING
Параметр `backup` нельзя использовать совместно с методами
балансировки нагрузки [hash](#s-u-hash) и [random](#s-u-random).
Параметры `down` и `drain` взаимно исключающие.
| `resolve` | Позволяет отслеживать изменения списка IP-адресов, соответствующего
доменному имени, и обновлять его без перезагрузки конфигурации.
При этом группа должна находиться в
[зоне разделяемой памяти](#s-u-zone);
также должен быть определен
[преобразователь имен в адреса](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-resolver). |
|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `service=`имя | Включает преобразование SRV-записей DNS и задает имя сервиса. При
указании этого параметра необходимо также задать параметр resolve,
не указывая порт сервера при имени хоста.
Если в имени службы нет точек, формируется имя по стандарту RFC:
к имени службы добавляется префикс `_`,
затем через точку добавляется `_tcp`.
Так, имя службы `http` даст в результате `_http._tcp`.
Angie разрешает SRV-записи,
объединяя нормализованное имя службы и имя хоста
и получая список серверов для полученной комбинации через DNS,
вместе с их приоритетами и весами.
- SRV-записи с наивысшим приоритетом
(те, которые имеют минимальное значение приоритета)
разрешаются как основные серверы,
а прочие записи становятся запасными серверами.
Если `backup` установлено с `server`,
SRV-записи с наивысшим приоритетом разрешаются как запасные серверы,
а прочие записи игнорируются.
- Вес аналогичен параметру `weight` директивы `server`.
Если вес задан как в самой директиве, так и в SRV-записи,
используется вес, установленный в директиве. |
В этом примере выполняется поиск записи `_http._tcp.backend.example.com`:
```nginx
server backend.example.com service=http resolve;
```
| `sid=`id | Задает ID сервера в группе. Если параметр не задан,
то ID задается как шестнадцатеричный MD5-хэш
IP-адреса и порта или пути UNIX-сокета. |
|------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| `slow_start=`время | Задает [время](https://angie.software//angie/docs/configuration/configfile.md#syntax) восстановления веса сервера,
возвращающегося к работе
при балансировке нагрузки методом
[round-robin](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#round-robin) или [least_conn](#s-u-least-conn).
Если параметр задан
и сервер после сбоя снова считается работающим
с точки зрения [max_fails](#s-max-fails) и [upstream_probe (PRO)](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe),
то такой сервер равномерно набирает указанный для него вес
в течение заданного времени.
Если параметр не задан,
то в аналогичной ситуации
сервер сразу начинает работу с указанным для него весом. |
|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### NOTE
Если в апстриме задан только один `server`,
`slow_start` не работает и будет игнорироваться.
### 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/<ИМЯ ФАЙЛА>;
}
```
Список серверов здесь имеет формат, аналогичный `s_server`.
Содержимое файла изменяется при любом изменении серверов в разделе
[/config/stream/upstreams/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-stream-upstreams-servers)
через API конфигурации.
Файл считывается при запуске Angie или перезагрузке конфигурации.
#### WARNING
Чтобы использовать директиву `state` в блоке `upstream`,
в нем не должно быть директив `server`,
но нужна зона разделяемой памяти ([zone](#s-u-zone)).
### zone
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `zone` имя [размер]; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | upstream |
Задает имя и размер зоны разделяемой памяти, в которой хранятся конфигурация группы и ее рабочее состояние, разделяемые между рабочими процессами. В одной и той же зоне могут быть сразу несколько групп. В этом случае достаточно указать размер только один раз.
#### NOTE
Содержимое зоны сохраняется при перезагрузке только в том случае, если
настроенный `размер` не изменился. Любое изменение — увеличение
или уменьшение — приводит к пересозданию зоны с потерей всех данных.
#### NOTE
Метрики группы собираются, только если настроена эта зона. Без нее группа
не отображается в [/status/stream/upstreams/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-upstreams),
в [виджете «TCP/UDP Upstreams»](https://angie.software//angie/docs/configuration/monitoring.md#tcp-udp-upstreams-widget)
и в выводе [Prometheus](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus),
и предупреждение при этом не выводится.
### backup_switch (PRO)
#### Versionadded
Добавлено в версии 1.10.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 media_backend {
zone media_backend 1m;
server primary1.example.com:1935;
server primary2.example.com:1935;
server reserve1.example.com:1935 backup;
server reserve2.example.com:1935 backup;
backup_switch permanent=2m;
}
```
Если балансировщик переключается с основных серверов на резервную группу,
все последующие запросы обрабатываются этой резервной группой в течение 2 минут.
По истечении 2 минут балансировщик повторно проверяет основные серверы
и снова делает их активными, если они работают нормально.
### feedback (PRO)
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `feedback` переменная [`inverse`] [`factor=`число] [`account=`условная_переменная]; |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | upstream |
Задает в `upstream` механизм балансировки нагрузки по обратной связи.
Он динамически корректирует решения при балансировке,
умножая вес каждого проксируемого сервера на среднее значение обратной связи,
которое меняется с течением времени в зависимости от значения переменной
и подчиняется необязательному условию.
Могут быть заданы следующие параметры:
| `переменная` | Переменная, из которой берется значение обратной связи.
Она должна представлять собой метрику производительности или состояния;
предполагается, что ее передает сервер.
Значение оценивается при каждом ответе от сервера
и учитывается в скользящем среднем
согласно настройкам `inverse` и `factor`. |
|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `inverse` | Если параметр задан, значение обратной связи интерпретируется наоборот:
более низкие значения указывают на лучшую производительность. |
| `factor` | Коэффициент, по которому значение обратной связи учитывается
при расчете среднего.
Допустимы целые числа от 0 до 99.
По умолчанию — `90`.
Среднее рассчитывается по формуле [экспоненциального сглаживания](https://ru.wikipedia.org/wiki/Экспоненциальное_сглаживание).
Чем больше коэффициент, тем меньше новые значения влияют на среднее;
если указать `90`, то будет взято 90 % от предыдущего значения
и лишь 10 % от нового. |
| `account` | Указывает условную переменную,
которая контролирует, как соединения учитываются при расчете.
Среднее значение обновляется с учетом значения обратной связи,
только если условная переменная
не равна `""` или `"0"`.
#### NOTE
По умолчанию трафик от [активных проверок](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe)
не включается в расчет;
комбинация переменной [$upstream_probe](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe)
с `account` позволяет включить и их
или даже исключить все остальное. |
Пример:
```nginx
upstream backend {
zone backend 1m;
feedback $feedback_value factor=80 account=$condition_value;
server backend1.example.com:1935 weight=1;
server backend2.example.com:1935 weight=2;
}
map $protocol $feedback_value {
"TCP" 100;
"UDP" 75;
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`
или обычные клиентские сессии.
### 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.
### 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) с учетом их весов.
### least_time (PRO)
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `least_time` `connect` | `first_byte` | `last_byte` [`factor=`number] [`account=`condition_variable]; |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | upstream |
Задает для группы метод балансировки нагрузки, при котором вероятность передачи
соединения активному серверу обратно пропорциональна среднему времени его
ответа; чем оно меньше, тем больше соединений будет получать сервер.
| `connect` | Директива учитывает среднее время установки соединения. |
|--------------|--------------------------------------------------------------------|
| `first_byte` | Директива использует среднее время получения первого байта ответа. |
| `last_byte` | Директива использует среднее время получения полного ответа. |
| `factor` | Выполняет ту же функцию, что и [response_time_factor (PRO)](#s-u-response-time-factor),
и переопределяет его, если параметр задан. |
|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `account` | Указывает условную переменную,
которая контролирует, какие соединения учитываются при расчете.
Среднее значение обновляется,
только если условная переменная соединения
не равна `""` или `"0"`.
#### NOTE
По умолчанию [активные проверки](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)
не включаются в расчет;
комбинация переменной [$upstream_probe](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe)
с `account` позволяет включить их
или даже исключить все остальное. |
Текущие значения представлены как `connect_time`, `first_byte_time`
и `last_byte_time` в объекте `health` сервера
среди [метрик апстрима](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-upstreams) в API.
### 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](#s-u-least-conn), при котором соединение передается на сервер с наименьшим количеством активных соединений.
### 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)](#s-u-least-time) коэффициент
сглаживания **предыдущего** значения при вычислении среднего времени ответа по формуле
[экспоненциально взвешенного скользящего среднего](https://ru.wikipedia.org/wiki/Скользящая_средняя#Экспоненциально_взвешенное_скользящее_среднее).
Чем больше указанное число, тем меньше новые значения влияют на среднее; если
указать `90`, то будет взято 90 % от предыдущего значения и лишь 10 % от
нового. Допустимые значения — от 0 до 99 включительно.
Текущие результаты вычислений представлены как `connect_time` (время
установления соединения), `first_byte_time` (время получения первого
байта ответа) и `last_byte_time` (время получения ответа целиком) в
объекте `health` сервера среди [метрик апстрима](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-upstreams) в API.
#### NOTE
При подсчете учитываются только успешные ответы; что считать неуспешным
ответом, определяют директивы [proxy_next_upstream](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-next-upstream).
### sticky
#### Versionchanged
Изменено в версии 1.10.0: PRO
#### Versionchanged
Изменено в версии 1.11.0: PRO
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `sticky route` значение...;
`sticky learn` `zone=`zone `create=`$create_var1... `lookup=`$lookup_var1... [`connect`] [`norefresh`] [`timeout=`time];
`sticky learn` `lookup=`$lookup_var1... `remote_action=`uri `remote_result=`$remote_var [`remote_uri=`uri]; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | upstream |
Настраивает привязку клиентских сессий к проксируемым серверам
в режиме, заданном первым параметром;
для разгрузки серверов,
у которых задана директива `sticky`,
можно использовать опцию `drain` (PRO) в блоке [server](#s-u-server).
#### WARNING
Директива `sticky` должна использоваться после всех директив,
задающих тот или иной метод балансировки нагрузки,
иначе она не будет работать.
Режим `route`
Этот режим использует предопределенные идентификаторы маршрутов,
которые могут быть встроены в свойства соединения, доступные Angie.
Он менее гибок, так как зависит от предопределенных значений,
но лучше подходит, если такие идентификаторы уже используются.
Здесь при установлении соединения проксируемый сервер
может назначить клиенту маршрут и вернуть его идентификатор способом,
известным им обоим.
В качестве идентификатора маршрута
должно использоваться значение параметра [sid](#s-reresolve)
директивы [server](#s-u-server).
Учтите, что параметр дополнительно хэшируется,
если задана директива [sticky_secret](#s-u-sticky-secret).
Последующие соединения от клиентов, желающих использовать этот маршрут,
должны содержать выданный сервером идентификатор, причем так,
чтобы он попал в переменные Angie.
В параметрах директивы указываются строки, которые могут содержать
переменные для маршрутизации. Чтобы выбрать сервер, куда направляется
входящее соединение, используется первое непустое значение;
она затем сравнивается с параметром [sid](#s-reresolve)
директивы [server](#s-u-server).
Если выбрать сервер не удается
или выбранный сервер не может принять соединение,
то будет выбран другой сервер
согласно настроенному методу балансировки.
Здесь Angie ищет идентификатор маршрута в переменной `$route`,
получающей значение на основе [$ssl_preread_server_name](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#v-ssl-preread-server-name)
(обратите внимание, что нужно включить [ssl_preread](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#s-ssl-preread)):
```nginx
stream {
map $ssl_preread_server_name $route {
a.example.com a;
b.example.com b;
default "";
}
upstream backend {
zone backend 1m;
server 127.0.0.1:8081 sid=a;
server 127.0.0.1:8082 sid=b;
sticky route $route;
}
server {
listen 127.0.0.1:8080;
ssl_preread on;
proxy_pass backend;
}
}
```
Режим `learn` (PRO)
В этом режиме для привязки клиента к конкретному проксируемому серверу
используется динамически генерируемый ключ;
этот режим более гибок,
так как назначает серверы на ходу,
хранит сеансы в зоне разделяемой памяти
и поддерживает различные способы передачи идентификаторов сессий.
Здесь сессия создается
на основе свойств соединения, идущих от проксируемого сервера.
С параметрами `create` и `lookup` перечисляются переменные,
указывающие, как создаются новые и ищутся существующие сессии.
Оба параметра можно использовать по нескольку раз.
Идентификатором сессии служит значение первой непустой переменной,
указанной с `create`;
например, это может быть
[имя проксируемого сервера](https://angie.software//angie/docs/configuration/modules/http/index.md#v-server-name).
Сессии хранятся в зоне разделяемой памяти;
ее имя и размер задаются параметром `zone`.
Если к сессии не было обращений в течение [времени](https://angie.software//angie/docs/configuration/configfile.md#syntax)
`timeout`, она удаляется.
Значение по умолчанию — 1 час.
По умолчанию Angie продлевает срок действия сессии,
обновляя метку времени последнего обращения при каждом ее использовании.
Параметр `norefresh` меняет это поведение:
сессия истекает строго по таймауту, даже если используется.
Последующие соединения от клиентов, желающих использовать сессию,
должны содержать ее идентификатор.
Параметр `lookup` ищет идентификатор сессии в соединении
по заданному для него списку переменных,
останавливаясь на первой непустой.
Если ничего не найдено — запрос считается новым.
Значение найденного идентификатора
сопоставляется с сессиями в разделяемой памяти.
Если выбрать сервер не удается
или выбранный сервер не может обработать соединение,
то будет выбран другой сервер
согласно настроенному методу балансировки.
Параметр `connect` позволяет создать сессию
сразу после установления соединения с проксируемым сервером.
Без него сессия создается только после завершения обработки соединения.
(В случае UDP-соединений сессии создаются сразу после выбора сервера.)
В примере Angie создает и ищет сессии,
используя переменную [$rdp_cookie](https://angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#v-rdp-cookie):
```nginx
stream {
upstream backend {
zone backend 1m;
server 127.0.0.1:3390;
server 127.0.0.1:3391;
sticky learn lookup=$rdp_cookie create=$rdp_cookie zone=sessions:1m;
}
server {
listen 127.0.0.1:3389;
rdp_preread on;
proxy_pass backend;
}
}
```
Режим `learn` с `remote_action` (PRO 1.10.0+)
Параметры `remote_action` и `remote_result`
позволяют динамически назначать идентификаторы сессий и управлять ими
с использованием удаленного хранилища сессий (PRO).
В отличие от режима `learn` с `zone`,
данный режим не кэширует сессии локально
и обращается к удаленному хранилищу при каждом соединении.
Параметр `remote_action` должен указывать на `location`
в контексте [client](https://angie.software//angie/docs/configuration/modules/http/index.md#client).
Параметр `remote_uri` задает URI клиентского HTTP-запроса
к указанному `location`.
По умолчанию он равен `/`.
Значение `remote_uri` может содержать переменные.
Общий принцип работы режима таков:
если идентификатор сессии не найден локально,
Angie отправляет синхронный подзапрос в некое удаленное хранилище,
заданное параметром `remote_action`.
При поступлении нового соединения Angie выполняет следующие действия:
- Сначала извлекается идентификатор сессии из первой непустой переменной
в списке `lookup`.
Если все переменные пустые,
используется обычный алгоритм балансировки нагрузки без привязки.
- Затем Angie отправляет в удаленное хранилище,
заданное параметром `remote_action`, синхронный HTTP-подзапрос,
который должен содержать в понятном хранилищу виде:
- идентификатор *сессии* из параметра `lookup`
(в конфигурации это переменная
[$sticky_sessid](#v-s-sticky-sessid));
- идентификатор предварительно выбранного *сервера*:
значение параметра `sid=` из директивы `server`,
если оно задано,
либо MD5-хэш имени сервера
(в конфигурации это переменная
[$sticky_sid](#v-s-sticky-sid)).
Переменные `$sticky_sessid` и `$sticky_sid` автоматически
экспортируются в HTTP-контекст c префиксом `stream_`:
`$stream_sticky_sessid`, `$stream_sticky_sid`.
Это позволяет напрямую использовать их в HTTP-директивах,
например через HTTP-заголовки с помощью [proxy_set_header](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-set-header).
- Удаленное хранилище обрабатывает запрос и возвращает HTTP-ответ:
Ответ с кодом 200, 201 или 204 подтверждает выбранный сервер.
Удаленное хранилище может одновременно с этим
вернуть альтернативный идентификатор сервера в HTTP-заголовке
или в теле ответа (PRO); извлечь его можно через `remote_result`.
При получении от хранилища любого другого HTTP-кода
(включая ошибки сети и таймауты)
либо несуществующего идентификатора сервера
Angie использует изначально выбранный сервер.
Идентификатор сервера извлекается из ответа удаленного хранилища
через параметр `remote_result`:
в нем можно указывать переменные
с префиксом `upstream_http_`,
которые создаются Angie автоматически для доступа
к заголовкам HTTP-ответов от удаленного хранилища,
или [$sent_body](https://angie.software//angie/docs/configuration/modules/http/index.md#v-sent-body) для использования тела ответа.
Например, заголовок `X-Sid: server1` в таком ответе
становится доступным в переменной `$upstream_http_x_sid`
со значением `server1`.
Ниже показан упрощенный пример конфигурации.
Удаленное хранилище возвращает идентификатор сервера в заголовке `X-Sticky-Sid`
и таким образом подтверждает или переопределяет выбор Angie:
```nginx
http {
client {
location @sticky_client1 {
# используем переменные из потокового upstream;
# он добавляет эти переменные в HTTP-контекст с префиксом stream_*
proxy_set_header X-Sticky-Sessid $stream_sticky_sessid;
proxy_set_header X-Sticky-Sid $stream_sticky_sid;
proxy_set_header X-Sticky-Last $msec;
proxy_pass http://127.0.0.1:8080;
proxy_cache remote;
proxy_cache_valid 200 1d;
proxy_cache_key $scheme$proxy_host$request_uri$stream_sticky_sessid;
}
}
}
stream {
upstream u {
zone u 1m;
server 127.0.0.1:8081 sid=backend-01;
server 127.0.0.1:8082 sid=backend-02;
sticky learn lookup=$remote_addr # переменная stream
remote_action=@sticky_client1 # location из блока client
remote_result=$upstream_http_x_sticky_sid # HTTP-переменная
remote_uri=/foo; # по умолчанию - /
}
server {
listen 127.0.0.1:8080;
proxy_pass u;
}
}
```
Здесь при следующем ответе от удаленного хранилища:
```none
HTTP/1.1 200 OK
...
X-Sticky-Sid: backend-01
X-Session-Info: active
```
Становятся доступными две переменные:
- `$upstream_http_x_sticky_sid`,
со значением `backend-01`;
- `$upstream_http_x_session_info`,
со значением `active`.
Так как переменная `$upstream_http_x_sticky_sid`
указана в параметре `remote_result`,
то ее значение будет использовано
для выбора сервера с `sid=backend-01`.
Директива `sticky` учитывает состояние серверов в [upstream](#s-u-upstream):
- Cерверы, помеченные как `down` или временно недоступные из-за сбоев,
исключаются из выбора.
- Cерверы, которые достигли максимального количества соединений
(при использовании `max_conns`), временно пропускаются.
- Cерверы с опцией `drain` (PRO)
могут быть выбраны для создания новых сессий в режиме `sticky`
при совпадении идентификаторов.
- Если ранее недоступный сервер восстанавливается,
`sticky` автоматически возобновляет его использование.
Поведение `sticky` можно дополнительно настроить
директивами [sticky_secret](#s-u-sticky-secret) и [sticky_strict](#s-u-sticky-strict).
Если в ходе работы `sticky` выбрать сервер не удается или он недоступен,
запрос будет обработан согласно выбранному методу балансировки нагрузки,
если только не включена директива `sticky_strict`.
В режиме `sticky_strict on;` запрос отклоняется с ошибкой.
Зоны разделяемой памяти,
указываемые в параметре `zone` директивы `sticky`,
не могут использоваться совместно различными `upstream`;
каждая группа должна использовать свою собственную зону.
### 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](#s-u-sticky) в режиме `route`.
Строка может содержать переменные, например `$remote_addr`:
```nginx
upstream backend {
zone backend 1m;
server 127.0.0.1:8081 sid=a;
server 127.0.0.1:8082 sid=b;
sticky route $route;
sticky_secret my_secret.$remote_addr;
}
```
Соль добавляется после хэшируемого значения;
чтобы независимо проверить механизм хэширования:
```console
$ echo -n "" | md5sum
```
### 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 будет возвращать клиенту ошибку соединения,
если желаемый сервер недоступен,
вместо использования любого другого доступного сервера,
как это происходит, когда в группе нет доступных серверов.
## Встроенные переменные
Модуль `stream_upstream` поддерживает следующие встроенные переменные:
### `$sticky_sessid`
Используется с `remote_action` в [sticky](#s-u-sticky);
хранит начальный идентификатор сессии, взятый из `lookup`.
### `$sticky_sid`
Используется с `remote_action` в [sticky](#s-u-sticky);
хранит идентификатор сервера, предварительно связанный с сессией.
В `sticky_sid` содержится значение параметра `sid=`
из блока [upstream](#s-u-upstream) директивы `server`, если оно задано,
либо MD5-хэш имени сервера.
### `$upstream_addr`
хранит IP-адрес и порт или путь к UNIX-сокету сервера группы. Если при проксировании были сделаны обращения к нескольким серверам, то их адреса разделяются запятой, например:
> 192.168.1.1:1935, 192.168.1.2:1935, unix:/tmp/sock"
Если сервер не может быть выбран, то переменная хранит имя [группы серверов](#s-u-upstream).
### `$upstream_bytes_received`
число байт, полученных от сервера группы. Значения нескольких соединений разделяются запятыми и двоеточиями подобно адресам в переменной [$upstream_addr](#v-s-upstream-addr).
### `$upstream_bytes_sent`
число байт, переданных на сервер группы. Значения нескольких соединений разделяются запятыми и двоеточиями подобно адресам в переменной [$upstream_addr](#v-s-upstream-addr).
### `$upstream_connect_time`
хранит время, затраченное на установление соединения с сервером группы; время хранится в секундах с точностью до миллисекунд. Времена нескольких соединений разделяются запятыми и двоеточиями подобно адресам в переменной [$upstream_addr](#v-s-upstream-addr).
### `$upstream_first_byte_time`
время получения первого байта данных; время хранится в секундах с точностью до миллисекунд. Времена нескольких соединений разделяются запятыми подобно адресам в переменной [$upstream_addr](#v-s-upstream-addr).
### `$upstream_session_time`
длительность сессии в секундах с точностью до миллисекунд. Времена нескольких соединений разделяются запятыми подобно адресам в переменной [$upstream_addr](#v-s-upstream-addr).
### `$upstream_sticky_status`
Статус соединений с привязкой.
| `""` | Соединение направлено в группу серверов, где привязка не используется. |
|--------|---------------------------------------------------------------------------------------|
| `NEW` | Соединение не содержит информации о привязке к серверу. |
| `HIT` | Соединение с привязкой направлено на желаемый сервер. |
| `MISS` | Соединение с привязкой направлено на сервер,
выбранный по алгоритму балансировки. |
Статусы из нескольких соединений разделяются запятыми и двоеточиями
аналогично адресам в переменной [$upstream_addr](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-addr).
# https://angie.software/angie/docs/configuration/modules/stream/stream_upstream_probe.md
# Upstream Probe
Реализует активные проверки работоспособности (health probes)
для [Upstream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream).
## Пример конфигурации
```nginx
server {
listen ...;
# ...
proxy_pass backend;
upstream_probe_timeout 1s;
upstream_probe backend_probe
port=12345
interval=5s
test=$good
essential
fails=3
passes=3
max_response=512k
mode=onfail
"send=data:GET / HTTP/1.0\r\n\r\n";
}
```
#### NOTE
Согласно спецификации RFC 2616 (HTTP/1.1) и RFC 9110 (HTTP Semantics),
заголовки HTTP должны разделяться последовательностью CRLF (`\r\n`), а
не просто `\n`.
## Директивы
### upstream_probe (PRO)
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `upstream_probe` имя [`port=`число] [`interval=`время] [`test=`условие] [`essential` [`persistent`]] [`fails=`число] [`passes=`число] [`max_response=`размер] [`mode=``always` | `idle` | `onfail`] [`udp`] [`send=`строка]; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server |
Задает активную проверку работоспособности серверов [апстрима](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream), указанного в директиве [proxy_pass](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-pass) в том же
контексте `server`, где находится директива `upstream_probe`.
Сервер проходит проверку, если запрос к нему успешно выполняется с учетом
всех параметров самой директивы `upstream_probe` и всех параметров,
влияющих на использование апстримов тем контекстом `server`, где она
задана, в том числе директивы [proxy_next_upstream](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-next-upstream).
Чтобы использовать проверки,
в апстриме необходима зона разделяемой памяти ([zone](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone)).
Для одного апстрима можно определить несколько проверок.
Могут быть заданы следующие параметры:
| `имя` | Обязательное имя проверки. |
|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `port` | Альтернативный порт для запроса. |
| `interval` | [Интервал](https://angie.software//angie/docs/configuration/configfile.md#syntax) между проверками.
По умолчанию — `5s`. |
| `test` | Проверяемое при запросе условие; задается строкой из переменных.
Если результат подстановки всех переменных — `""` или `"0"`,
проверка не пройдена. |
| `essential` | Если параметр задан, то изначально состояние сервера подлежит уточнению
и клиентские запросы не передаются ему, пока проверка не будет пройдена. |
| `persistent` | Установка этого параметра требует сначала включить `essential`;
серверы с `persistent`, работавшие до
[перезагрузки конфигурации](https://angie.software//angie/docs/configuration/configfile.md#configfile-reloading),
начинают получать запросы без необходимости сначала пройти эту проверку. |
| `fails` | Число последовательных неуспешных запросов,
при котором проверка считает сервер неработающим.
По умолчанию — 1. |
| `passes` | Число последовательных успешных запросов,
при котором проверка считает сервер работающим.
По умолчанию — 1. |
| `max_response` | Максимальный объем памяти для ответа. Если задано нулевое
[значение](https://angie.software//angie/docs/configuration/configfile.md#syntax), ожидание ответа отключается.
По умолчанию — `256k`. |
| `mode` | Режим проверки в зависимости от работоспособности серверов:
- `always` — серверы проверяются независимо от состояния;
- `idle` — проверяются неработающие серверы, а также серверы,
где с последнего клиентского запроса прошло время `interval`.
- `onfail` — проверяются серверы только в неработающем состоянии.
По умолчанию — `always`. |
| `udp` | Если параметр указан, используется протокол UDP.
По умолчанию для проверок используется TCP. |
| `send` | Отправляемые для проверки данные: встроенные данные с префиксом `data:`
или путь к файлу (абсолютный или относительно `/usr/local/angie/`).
При использовании файла:
- [Рабочий процесс](https://angie.software//angie/docs/configuration/modules/core.md#worker-processes) открывает и читает
файл при каждом обращении; содержимое не сохраняется в памяти.
- Перезагрузка конфигурации при изменении файла не требуется;
новое содержимое будет прочитано при следующем обращении.
- Необходимые права доступа: `644` для файла,
`755` для директории.
- Обновляйте файлы командой перемещения (`mv`),
а не прямым редактированием. |
Пример:
```nginx
upstream backend {
zone backend 1m;
server a.example.com;
server b.example.com;
}
map $upstream_probe_response $good {
~200 "1";
default "";
}
server {
listen ...;
# ...
proxy_pass backend;
upstream_probe_timeout 1s;
upstream_probe backend_probe
port=12345
interval=5s
test=$good
essential
persistent
fails=3
passes=3
max_response=512k
mode=onfail
"send=data:GET / HTTP/1.0\r\n\r\n";
}
```
Детали работы:
- Изначально сервер не получает клиентские запросы,
пока не пройдет *все* заданные для него проверки с параметром `essential`
(пропуская помеченные как `persistent`, если конфигурация перезагружена
и до этого сервер считался работающим).
Если таких проверок нет, сервер считается работающим.
- Сервер считается неработающим и не получает клиентские запросы,
если *какая-либо* заданная для него проверка достигает своего порога `fails`
или сам сервер достигает порога [max_fails](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails).
- Чтобы неработающий сервер снова мог считаться работающим,
*все* заданные для него проверки должны достичь своего порога `passes`;
после этого учитывается порог [max_fails](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails).
### upstream_probe_timeout (PRO)
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `upstream_probe_timeout` время; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `upstream_probe_timeout 50s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server |
Задает максимальное [время](https://angie.software//angie/docs/configuration/configfile.md#syntax) бездействия
установленного с сервером соединения
для проверок, настроенных с помощью директивы [upstream_probe (PRO)](#s-u-upstream-probe);
при превышении этого предела соединение будет закрыто.
## Встроенные переменные
Модуль `stream_upstream` поддерживает следующие встроенные переменные:
### `$upstream_probe` (PRO)
Имя активной сейчас проверки [upstream_probe](#s-u-upstream-probe).
### `$upstream_probe_response` (PRO)
Содержимое ответа,
полученного в ходе активной проверки [upstream_probe](#s-u-upstream-probe).
# https://angie.software/angie/docs/configuration/modules/mail.md
# Почтовый модуль
Базовый почтовый модуль реализует основную функциональность почтового
прокси-сервера: это поддержка протоколов SMTP, IMAP и POP3, настройка серверных
блоков, маршрутизация почтовых запросов, аутентификация пользователей и
поддержка SSL/TLS для защиты почтовых соединений.
Остальные модули этого раздела расширяют эту функциональность, позволяя гибко
настраивать и оптимизировать работу почтового сервера под различные сценарии и
требования.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑mail`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
## Пример конфигурации
```nginx
worker_processes auto;
error_log /var/log/angie/error.log info;
events {
worker_connections 1024;
}
mail {
server_name mail.example.com;
auth_http localhost:9000/cgi-bin/auth.cgi;
imap_capabilities IMAP4rev1 UIDPLUS IDLE LITERAL+ QUOTA;
pop3_auth plain apop cram-md5;
pop3_capabilities LAST TOP USER PIPELINING UIDL;
smtp_auth login plain cram-md5;
smtp_capabilities "SIZE 10485760" ENHANCEDSTATUSCODES 8BITMIME DSN;
xclient off;
server {
listen 25;
protocol smtp;
}
server {
listen 110;
protocol pop3;
proxy_pass_error_message on;
}
server {
listen 143;
protocol imap;
}
server {
listen 587;
protocol smtp;
}
}
```
## Директивы
### listen
#### Versionchanged
Изменено в версии 1.10.0.
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `listen` адрес[:порт] [`ssl`] [`proxy_protocol`] [`backlog=`число] [`rcvbuf=`размер] [`sndbuf=`размер] [`bind`] [`ipv6only=``on` | `off`] [`reuseport`] [`so_keepalive=`on|off|[`keepidle`]:[`keepintvl`]:[`keepcnt`]]; |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server |
Задает адрес и порт для сокета, на котором сервер будет принимать соединения. Можно указать только порт, и тогда Angie будет слушать на всех доступных IPv4-интерфейсах (и IPv6, если он включен). Кроме того, адрес может быть именем хоста, например:
```nginx
listen 127.0.0.1:110;
listen *:110;
listen 110; # то же, что и *:110
listen localhost:110;
```
IPv6-адреса задаются в квадратных скобках:
```nginx
listen [::1]:110;
listen [::]:110;
```
UNIX-сокеты задаются префиксом `unix:`
```nginx
listen unix:/var/run/angie.sock;
```
#### NOTE
Разные серверы должны слушать на разных парах адрес:порт.
| `ssl` | указывает на то, что все соединения, принимаемые на данном слушающем сокете, должны работать в режиме SSL. |
|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `proxy_protocol` | указывает на то, что все соединения, принимаемые на данном порту, должны использовать протокол PROXY. Полученная информация передается [серверу аутентификации](https://angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#mail-auth-http) и может быть использована для [изменения адреса клиента](https://angie.software//angie/docs/configuration/modules/mail/mail_realip.md#mail-realip). |
В директиве `listen` можно также указать несколько дополнительных параметров, специфичных для связанных с сокетами системных вызовов.
| `backlog=`число | задает параметр backlog в вызове listen(), который ограничивает максимальный размер очереди ожидающих приема соединений. По умолчанию backlog устанавливается равным -1 для FreeBSD, DragonFly BSD и macOS, и 511 для других платформ. |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `rcvbuf=`размер | задает размер буфера приема (параметр SO_RCVBUF) для слушающего сокета. |
| `sndbuf=`размер | задает размер буфера передачи (параметр SO_SNDBUF) для слушающего сокета. |
| `bind` | указывает, что для данного слушающего сокета нужно делать bind() отдельно. Это нужно потому, что если описаны несколько директив `listen` с одинаковым портом, но разными адресами, и одна из директив `listen` слушает на всех адресах для данного порта (\*:порт), то Angie сделает bind() только на \*:порт. Необходимо заметить, что в этом случае для определения адреса, на который пришло соединение, делается системный вызов getsockname(). Если же используются параметры backlog, rcvbuf, sndbuf, ipv6only, reuseport или so_keepalive, то для данной пары адрес:порт всегда делается отдельный вызов bind(). |
| `ipv6only=on` | `off` | определяет (через параметр сокета `IPV6_V6ONLY`), будет ли слушающий на wildcard-адресе [::] IPv6-сокет принимать только IPv6-соединения, или же одновременно IPv6- и IPv4-соединения. По умолчанию параметр включен. Установить его можно только один раз на старте. |
| `multipath` | включает прием соединений по протоколу [Multipath TCP](https://en.wikipedia.org/wiki/Multipath_TCP) (MPTCP),
поддерживаемому в ядре Linux с версии 5.6. |
`so_keepalive=on` | `off` | [`keepidle`]:[`keepintvl`]:[`keepcnt`]
Конфигурирует для слушающего сокета поведение "TCP keepalive".
| `''` | если параметр опущен, для сокета будут действовать настройки операционной системы |
|--------|-------------------------------------------------------------------------------------|
| `on` | для сокета включается параметр SO_KEEPALIVE |
| `off` | для сокета параметр SO_KEEPALIVE выключается |
Некоторые операционные системы поддерживают настройку параметров "TCP keepalive"
на уровне сокета посредством параметров `TCP_KEEPIDLE`, `TCP_KEEPINTVL` и
`TCP_KEEPCNT`. На таких системах их можно сконфигурировать с помощью параметров
`keepidle`, `keepintvl` и `keepcnt`. Один или два параметра могут быть опущены,
в таком случае для соответствующего параметра сокета будут действовать
стандартные системные настройки.
Например,
```nginx
so_keepalive=30m::10
```
установит таймаут бездействия (`TCP_KEEPIDLE`) в 30 минут, для интервала проб (`TCP_KEEPINTVL`) будет действовать стандартная системная настройка, а счетчик проб (`TCP_KEEPCNT`) будет равен 10.
Разные серверы должны слушать на разных парах адрес:порт.
### mail
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `mail` { ... } |
|------------------------------------------------------------------------------------------|------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | main |
Предоставляет контекст конфигурационного файла, в котором указываются директивы почтового сервера.
### max_commands
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `max_commands` число; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | `max_commands 1000;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает максимальное количество команд, отправляемых во время аутентификации,
для усиления защиты от DoS-атак.
### max_errors
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `max_errors` число; |
|------------------------------------------------------------------------------------------|-----------------------|
| По умолчанию | `max_errors 5;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает число ошибок протокола, по достижении которого соединение закрывается.
### protocol
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `protocol` imap | pop3 | smtp; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server |
Задает протокол проксируемого сервера. Поддерживаются протоколы [IMAP](https://angie.software//angie/docs/configuration/modules/mail/mail_imap.md#mail-imap), [POP3](https://angie.software//angie/docs/configuration/modules/mail/mail_pop3.md#mail-pop3) и [SMTP](https://angie.software//angie/docs/configuration/modules/mail/mail_smtp.md#mail-smtp).
Если директива не указана, то протокол может быть определен автоматически по общеизвестному порту, указанному в директиве `listen`:
```console
imap: 143, 993
pop3: 110, 995
smtp: 25, 587, 465
```
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) поддержку
ненужных протоколов можно отключить с помощью [параметров сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure) `‑‑without‑mail_imap_module`,
`‑‑without‑mail_pop3_module` и `‑‑without‑mail_smtp_module`.
### resolver
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `resolver` адрес ... [`valid=`время] [`ipv4=``on` | `off`] [`ipv6=``on` | `off`] [`status_zone=`зона] | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `resolver off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает серверы DNS, используемые для преобразования имени хоста клиента для передачи его на [сервер аутентификации](https://angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#mail-auth-http) и в команде [XCLIENT](https://angie.software//angie/docs/configuration/modules/mail/mail_proxy.md#m-xclient) при проксировании SMTP, например:
```nginx
resolver 127.0.0.53 [::1]:5353;
```
Специальное значение `off` отключает преобразование имени хоста клиента и отменяет унаследованное значение директивы.
Адрес может быть указан в виде доменного имени или IP-адреса, и необязательного порта.
Если порт не указан, используется порт 53. Серверы DNS опрашиваются циклически.
#### NOTE
Рекомендуется использовать локальный доверенный резолвер, например
`127.0.0.53` (systemd-resolved), а не публичный (например, `8.8.8.8`).
Публичные резолверы раскрывают DNS-запросы третьим сторонам и повышают
риск атак с подменой кэша.
#### NOTE
Значение директивы наследуется вложенными блоками
и может быть переопределено в них при необходимости.
В пределах одного блока допустимо указывать директиву только один раз.
Если она повторяется, действует последнее определение.
По умолчанию Angie кэширует ответы, используя значение TTL из ответа DNS. Если
директива `resolver` не указана и не выполняются динамические DNS-запросы
(например, при использовании фиксированных имен в [Proxy](https://angie.software//angie/docs/configuration/modules/mail/mail_proxy.md#mail-proxy) без
переменных), указание резолвера не требуется: имена будут разрешены при запуске
с помощью системного резолвера. Необязательный параметр `valid` позволяет
это переопределить:
| `valid` | *необязательный* параметр, позволяет переопределить срок кэширования ответа |
|-----------|--------------------------------------------------------------------------------|
```nginx
resolver 127.0.0.53 [::1]:5353 valid=30s;
```
По умолчанию Angie будет искать как IPv4-, так и IPv6-адреса при преобразовании имен в адреса.
| `ipv4=off` | запрещает поиск IPv4-адресов |
|---------------|-------------------------------------------------------------------------------------------------------|
| `ipv6=off` | запрещает поиск IPv6-адресов |
| `status_zone` | *необязательный* параметр, включает сбор информации о запросах и ответах сервера DNS в указанной зоне |
### resolver_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `resolver_timeout` время; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `resolver_timeout 30s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает таймаут для преобразования имени в адрес, например:
```nginx
resolver_timeout 5s;
```
### server
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `server` { ... } |
|------------------------------------------------------------------------------------------|--------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail |
Задает конфигурацию для сервера.
### server_name
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `server_name` имя; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | `server_name hostname`; |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает имя сервера, используемое:
* в начальном приветствии POP3/SMTP-сервера;
* в salt при аутентификации SASL-методом CRAM-MD5;
* в команде EHLO при подключении к SMTP-бэкенду, если разрешена передача команды [XCLIENT](https://angie.software//angie/docs/configuration/modules/mail/mail_proxy.md#m-xclient).
Если директива не указана, используется имя хоста (hostname) машины.
### timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `timeout` время; |
|------------------------------------------------------------------------------------------|--------------------|
| По умолчанию | `timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает таймаут, который используется до начала проксирования на бэкенд.
# https://angie.software/angie/docs/configuration/modules/mail/mail_auth_http.md
# Auth HTTP
Модуль позволяет выполнять аутентификацию на основе дополнительного HTTP-запроса
перед обработкой основного запроса. Если подзапрос возвращает статус 2xx,
основной запрос продолжается; если возвращается 401 или 403, пользователю
отправляется соответствующая ошибка, а при любом другом статусе возвращается
ошибка 500. Такой подход обычно используется для передачи аутентификации внешним
сервисам, объединения аутентификации в разных приложениях или интеграции со
сторонними системами, такими как OAuth или LDAP.
## Директивы
### auth_http
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_http` uri; |
|------------------------------------------------------------------------------------------|--------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает URL HTTP-сервера аутентификации. Протокол описан [ниже](#v-m-protocol).
### auth_http_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_http_header` заголовок значение; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Добавляет указанный заголовок к запросам, посылаемым на сервер аутентификации. Заголовок можно использовать в качестве shared secret для проверки, что запрос поступил от Angie. Например:
```nginx
auth_http_header X-Auth-Key "secret_string";
```
### auth_http_pass_client_cert
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_http_pass_client_cert` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | `auth_http_pass_client_cert off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Добавляет заголовок `Auth-SSL-Cert` с [клиентским сертификатом](https://angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-ssl-verify-client) в формате PEM (закодирован в формате urlencode) к запросам, посылаемым на сервер аутентификации.
### auth_http_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_http_timeout` время; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `auth_http_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает таймаут общения с сервером аутентификации.
## Протокол
Для общения с сервером аутентификации используется протокол HTTP. Данные в теле ответа игнорируются, информация передается только в заголовках.
### Примеры запросов и ответов:
Запрос:
```console
GET /auth HTTP/1.0
Host: localhost
Auth-Method: plain # plain/apop/cram-md5/external/xoauth2/oauthbearer/none
Auth-User: user
Auth-Pass: password
Auth-Protocol: imap # imap/pop3/smtp
Auth-Login-Attempt: 1
Client-IP: 192.0.2.42
Client-Host: client.example.org
```
Хороший ответ:
```console
HTTP/1.0 200 OK
Auth-Status: OK
Auth-Server: 198.51.100.1
Auth-Port: 143
```
Плохой ответ:
```console
HTTP/1.0 200 OK
Auth-Status: Invalid login or password
Auth-Wait: 3
```
Если заголовка `Auth-Wait` нет, то после выдачи ошибки соединение будет закрыто. В текущей реализации на каждую попытку аутентификации выделяется память, которая освобождается только при завершении сессии. Поэтому число неудачных попыток аутентификации в рамках одной сессии должно быть ограничено — после 10-20 попыток (номер попытки передается в заголовке `Auth-Login-Attempt`) сервер должен выдать ответ без заголовка `Auth-Wait`.
При использовании APOP или CRAM-MD5 запрос и ответ будут выглядеть так:
```console
GET /auth HTTP/1.0
Host: localhost
Auth-Method: apop
Auth-User: user
Auth-Salt: <238188073.1163692009@mail.example.com>
Auth-Pass: auth_response
Auth-Protocol: imap
Auth-Login-Attempt: 1
Client-IP: 192.0.2.42
Client-Host: client.example.org
```
Хороший ответ:
```console
HTTP/1.0 200 OK
Auth-Status: OK
Auth-Server: 198.51.100.1
Auth-Port: 143
Auth-Pass: plain-text-pass
```
При использовании XOAUTH2 или OAUTHBEARER заголовки `Auth-User` и
`Auth-Pass` содержат имя пользователя и токен bearer, извлеченные из
начального SASL-ответа.
Если в ответе есть заголовок `Auth-User`, то он переопределяет имя пользователя, используемое для аутентификации с бэкендом.
Для SMTP в ответе дополнительно учитывается заголовок `Auth-Error-Code` — если он есть, то используется как код ответа в случае ошибки. Если его нет, то по умолчанию к `Auth-Status` будет добавлен код 535 5.7.0.
Для XOAUTH2 и OAUTHBEARER в ответе с ошибкой также может присутствовать
заголовок `Auth-Error-SASL`. Его значение отправляется клиенту как
дополнительный SASL-вызов (SMTP: 334, IMAP/POP3: +). После ответа клиента
(пустой ответ для XOAUTH2 или `AQ==` для OAUTHBEARER) будет возвращена
ошибка из `Auth-Status`.
Например, если от сервера аутентификации будет получен ответ:
```console
HTTP/1.0 200 OK
Auth-Status: Temporary server problem, try again later
Auth-Error-Code: 451 4.3.0
Auth-Wait: 3
```
то по SMTP клиенту будет выдана ошибка
```console
451 4.3.0 Temporary server problem, try again later
```
Если при проксировании SMTP не требуется аутентификация, запрос будет выглядеть так:
```console
GET /auth HTTP/1.0
Host: localhost
Auth-Method: none
Auth-User:
Auth-Pass:
Auth-Protocol: smtp
Auth-Login-Attempt: 1
Client-IP: 192.0.2.42
Client-Host: client.example.org
Auth-SMTP-Helo: client.example.org
Auth-SMTP-From: MAIL FROM: <>
Auth-SMTP-To: RCPT TO:
```
Для клиентского соединения по протоколу SSL/TLS добавляется заголовок `Auth-SSL`, и если директива [ssl_verify_client](https://angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-ssl-verify-client) включена, заголовок `Auth-SSL-Verify` содержит результат проверки клиентского сертификата: `SUCCESS`, `FAILED:reason` и, если сертификат не был предоставлен, `NONE`.
Если клиентский сертификат был предоставлен, информация о нем передается в следующих заголовках запроса: `Auth-SSL-Subject`, `Auth-SSL-Issuer`, `Auth-SSL-Serial` и `Auth-SSL-Fingerprint`. Если директива [auth_http_pass_client_cert](#m-auth-http-pass-client-cert) включена, сам сертификат передается в заголовке `Auth-SSL-Cert`. Протокол и шифр установленного соединения передаются в заголовках `Auth-SSL-Protocol` и `Auth-SSL-Cipher`. Запрос будет выглядеть так:
```console
GET /auth HTTP/1.0
Host: localhost
Auth-Method: plain
Auth-User: user
Auth-Pass: password
Auth-Protocol: imap
Auth-Login-Attempt: 1
Client-IP: 192.0.2.42
Auth-SSL: on
Auth-SSL-Protocol: TLSv1.3
Auth-SSL-Cipher: TLS_AES_256_GCM_SHA384
Auth-SSL-Verify: SUCCESS
Auth-SSL-Subject: /CN=example.com
Auth-SSL-Issuer: /CN=example.com
Auth-SSL-Serial: C07AD56B846B5BFF
Auth-SSL-Fingerprint: 29d6a80a123d13355ed16b4b04605e29cb55a5ad
```
При использовании [протокола PROXY](https://angie.software//angie/docs/configuration/modules/mail/index.md#m-listen-ssl-proxy), информация о нем передается в следующих заголовках запроса: `Proxy-Protocol-Addr`, `Proxy-Protocol-Port`, `Proxy-Protocol-Server-Addr` и `Proxy-Protocol-Server-Port`.
# https://angie.software/angie/docs/configuration/modules/mail/mail_imap.md
# IMAP
Модуль обеспечивает поддержку почтового протокола IMAP, позволяя серверу
взаимодействовать с системами хранения почты. Он устанавливает соединения с
серверами IMAP, обрабатывает основные команды, такие как список папок и
получение сообщений, а также обеспечивает безопасную аутентификацию и управление
статусами сообщений.
## Директивы
### imap_auth
#### Versionchanged
Изменено в версии 1.11.0.
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `imap_auth` метод ...; |
|------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию | `imap_auth plain;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает разрешенные методы аутентификации IMAP-клиентов. Поддерживаемые методы:
| `plain` | [LOGIN](https://datatracker.ietf.org/doc/html/rfc3501), [AUTH=PLAIN](https://datatracker.ietf.org/doc/html/rfc4616) |
|---------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| `login` | [AUTH=LOGIN](https://datatracker.ietf.org/doc/html/draft-murchison-sasl-login-00) |
| `cram-md5` | [AUTH=CRAM-MD5](https://datatracker.ietf.org/doc/html/rfc2195). Для работы этого метода пароль должен храниться в незашифрованном виде. |
| `external` | [AUTH=EXTERNAL](https://datatracker.ietf.org/doc/html/rfc4422) |
| `xoauth2` | [AUTH=XOAUTH2](https://developers.google.com/gmail/imap/xoauth2-protocol) |
| `oauthbearer` | [AUTH=OAUTHBEARER](https://datatracker.ietf.org/doc/html/rfc7628) |
Методы аутентификации с передачей пароля открытым текстом (команда LOGIN, AUTH=PLAIN и AUTH=LOGIN) включены всегда, однако если методы `plain` и `login` не указаны, то AUTH=PLAIN и AUTH=LOGIN не будут автоматически добавляться в [imap_capabilities](#m-imap-capabilities).
### imap_capabilities
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `imap_capabilities` расширение ...; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | `imap_capabilities IMAP4 IMAP4rev1 UIDPLUS;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Позволяет указать список расширений [протокола IMAP](https://datatracker.ietf.org/doc/html/rfc3501), выдаваемый клиенту по команде CAPABILITY. В зависимости от значения директивы [starttls](https://angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-starttls) к этому списку автоматически добавляются методы аутентификации, указанные в директиве [imap_auth](#m-imap-auth), и [STARTTLS](https://datatracker.ietf.org/doc/html/rfc2595).
В данной директиве имеет смысл указать расширения, поддерживаемые IMAP-серверами, на которые проксируются клиенты (если эти расширения относятся к командам, используемым после аутентификации, когда Angie прозрачно проксирует подключение клиента на бэкенд).
### imap_client_buffer
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `imap_client_buffer` размер; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `imap_client_buffer 4k|8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает размер буфера для чтения IMAP-команд. По умолчанию размер одного буфера равен размеру страницы. В зависимости от платформы это или 4K, или 8K.
# https://angie.software/angie/docs/configuration/modules/mail/mail_pop3.md
# POP3
Модуль обеспечивает поддержку почтового протокола POP3, позволяя серверу
загружать сообщения с почтовых серверов. Он подключается к серверам POP3,
получает заголовки и содержимое сообщений, обеспечивает безопасную
аутентификацию и управляет статусами сообщений, такими как загружено или
удалено.
## Директивы
### pop3_auth
#### Versionchanged
Изменено в версии 1.11.0.
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `pop3_auth` метод ...; |
|------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию | `pop3_auth plain;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает разрешенные методы аутентификации POP3-клиентов. Поддерживаемые методы:
| `plain` | [USER/PASS](https://datatracker.ietf.org/doc/html/rfc1939), [AUTH PLAIN](https://datatracker.ietf.org/doc/html/rfc4616), [AUTH LOGIN](https://datatracker.ietf.org/doc/html/draft-murchison-sasl-login-00) |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `apop` | [APOP](https://datatracker.ietf.org/doc/html/rfc1939). Для работы этого метода пароль должен храниться в незашифрованном виде. |
| `cram-md5` | [AUTH=CRAM-MD5](https://datatracker.ietf.org/doc/html/rfc2195). Для работы этого метода пароль должен храниться в незашифрованном виде. |
| `external` | [AUTH=EXTERNAL](https://datatracker.ietf.org/doc/html/rfc4422) |
| `xoauth2` | [AUTH=XOAUTH2](https://developers.google.com/gmail/imap/xoauth2-protocol) |
| `oauthbearer` | [AUTH=OAUTHBEARER](https://datatracker.ietf.org/doc/html/rfc7628) |
Методы аутентификации с передачей пароля открытым текстом (`USER/PASS`, `AUTH PLAIN` и `AUTH LOGIN`) включены всегда, однако если метод `plain` не указан, то AUTH PLAIN и AUTH LOGIN не будут автоматически добавляться в [pop3_capabilities](#m-pop3-capabilities).
### pop3_capabilities
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `pop3_capabilities` расширение ...; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `pop3_capabilities TOP USER UIDL;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Позволяет указать список расширений [протокола POP3](https://datatracker.ietf.org/doc/html/rfc2449), выдаваемый клиенту по команде CAPA. В зависимости от значения директивы [starttls](https://angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-starttls) к этому списку автоматически добавляются методы аутентификации, указанные в директиве [pop3_auth](#m-pop3-auth) (расширение [SASL](https://datatracker.ietf.org/doc/html/rfc2449)), и [STLS](https://datatracker.ietf.org/doc/html/rfc2595).
В данной директиве имеет смысл указать расширения, поддерживаемые POP3-серверами, на которые проксируются клиенты (если эти расширения относятся к командам, используемым после аутентификации, когда Angie прозрачно проксирует подключение клиента на бэкенд).
# https://angie.software/angie/docs/configuration/modules/mail/mail_proxy.md
# Proxy
Модуль обеспечивает поддержку почтовых протоколов (POP3, IMAP, SMTP), позволяя
серверу работать в качестве прокси между клиентами и почтовыми серверами. Он
устанавливает соединения с серверами, выполняет безопасную аутентификацию с
использованием открытого текста, SSL/TLS или STARTTLS, правильно маршрутизирует
трафик клиентов и поддерживает гибкий выбор методов аутентификации и серверов.
## Директивы
### proxy_buffer
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_buffer` размер; |
|------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию | `proxy_buffer 4k|8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает размер буфера, используемого при проксировании. По умолчанию размер одного буфера равен размеру страницы. В зависимости от платформы это или 4K, или 8K.
### proxy_pass_error_message
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_pass_error_message` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `proxy_pass_error_message off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Определяет, передавать ли клиенту сообщение об ошибке, полученное при аутентификации на бэкенде.
Обычно, если аутентификация в Angie прошла успешно, бэкенд не может вернуть ошибку. Если же он все-таки возвращает ошибку, это значит, что произошла ошибка внутри системы. В таких случаях сообщение бэкенда может содержать информацию, которую нельзя показывать клиенту. Однако для некоторых POP3-серверов ошибка в ответ на правильный пароль является штатным поведением. В этом случае директиву стоит включить.
### proxy_protocol
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_protocol` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `proxy_protocol off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Включает [протокол PROXY](http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) для соединений с бэкендом.
### proxy_smtp_auth
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_smtp_auth` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `proxy_smtp_auth off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Разрешает или запрещает аутентификацию пользователей на SMTP-бэкенде при помощи команды `AUTH`.
Если также включен [XCLIENT](#m-xclient), то команда `XCLIENT` не будет отправлять параметр `LOGIN`.
### proxy_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_timeout` время; |
|------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию | `proxy_timeout 24h;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает таймаут между двумя идущими подряд операциями чтения или записи на клиентском соединении или соединении с проксируемым сервером. Если по истечении этого времени данные не передавались, соединение закрывается.
### xclient
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `xclient` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------|
| По умолчанию | `xclient on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Разрешает или запрещает передачу команды [XCLIENT](http://www.postfix.org/XCLIENT_README.html) с параметрами клиента при подключении к SMTP-бэкенду.
При помощи `XCLIENT` MTA может писать в лог информацию о клиенте и применять различные ограничения на основе этих данных.
Если команда `XCLIENT` разрешена, то при подключении к бэкенду Angie посылает ему следующие команды:
* `EHLO` с [именем сервера](https://angie.software//angie/docs/configuration/modules/mail/index.md#m-server-name)
* `XCLIENT`
* `EHLO` или `HELO`, как ее передал клиент
Если [найденное](https://angie.software//angie/docs/configuration/modules/mail/index.md#m-resolver) по IP-адресу клиента имя указывает на тот же
адрес, оно передается в параметре `NAME` команды `XCLIENT`. Если имя
не может быть найдено, указывает на другой адрес, или не задан [resolver](https://angie.software//angie/docs/configuration/modules/mail/index.md#m-resolver), то в параметре `NAME` передается `[UNAVAILABLE]`.
Если же в процессе поиска имени или адреса произошла ошибка, передается
`[TEMPUNAVAIL]`.
Если команда `XCLIENT` запрещена, то при подключении к бэкенду Angie
передает команду `EHLO` с [именем сервера](https://angie.software//angie/docs/configuration/modules/mail/index.md#m-server-name), если
клиент передал `EHLO`, иначе `HELO` с именем сервера.
# https://angie.software/angie/docs/configuration/modules/mail/mail_realip.md
# RealIP
Позволяет менять адрес и необязательный порт клиента на переданные в указанном
поле заголовка адрес и порт клиента на переданные в заголовке протокола PROXY.
Протокол PROXY должен быть предварительно включен при помощи установки параметра
`proxy_protocol` в директиве [listen](https://angie.software//angie/docs/configuration/modules/mail/index.md#m-listen).
## Пример конфигурации
```nginx
listen 110 proxy_protocol;
set_real_ip_from 192.168.1.0/24;
set_real_ip_from 192.168.2.1;
set_real_ip_from 2001:0db8::/32;
```
## Директивы
### set_real_ip_from
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `set_real_ip_from` адрес | CIDR | `unix:`; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает доверенные адреса, которые передают верный адрес для замены. Если указано специальное значение `unix:`, доверенными будут считаться все UNIX-сокеты.
# https://angie.software/angie/docs/configuration/modules/mail/mail_smtp.md
# SMTP
Модуль обеспечивает поддержку почтового протокола SMTP, позволяя серверу
проксировать исходящий почтовый трафик между клиентами и почтовыми серверами. Он
устанавливает соединения с серверами SMTP, поддерживает безопасную
аутентификацию с помощью методов LOGIN или PLAIN, обеспечивает шифрование через
STARTTLS и SSL/TLS и маршрутизирует клиентские запросы на основе результатов
аутентификации.
## Директивы
### smtp_auth
#### Versionchanged
Изменено в версии 1.11.0.
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `smtp_auth` метод ...; |
|------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию | `smtp_auth plain login;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает разрешенные методы [SASL-аутентификации](https://datatracker.ietf.org/doc/html/rfc2554) SMTP-клиентов. Поддерживаемые методы:
| `plain` | [AUTH PLAIN](https://datatracker.ietf.org/doc/html/rfc4616) |
|---------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| `login` | [AUTH LOGIN](https://datatracker.ietf.org/doc/html/draft-murchison-sasl-login-00) |
| `cram-md5` | [AUTH CRAM-MD5](https://datatracker.ietf.org/doc/html/rfc2195). Для работы этого метода пароль должен храниться в незашифрованном виде. |
| `external` | [AUTH EXTERNAL](https://datatracker.ietf.org/doc/html/rfc4422) |
| `xoauth2` | [AUTH XOAUTH2](https://developers.google.com/gmail/imap/xoauth2-protocol) |
| `oauthbearer` | [AUTH OAUTHBEARER](https://datatracker.ietf.org/doc/html/rfc7628) |
| `none` | Аутентификация не требуется |
Методы аутентификации с передачей пароля открытым текстом (`AUTH PLAIN` и `AUTH LOGIN`) включены всегда, однако если методы `plain` и `login` не указаны, то `AUTH PLAIN` и `AUTH LOGIN` не будут автоматически добавляться в [smtp_capabilities](#m-smtp-capabilities).
### smtp_capabilities
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `smtp_capabilities` расширение ...; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Позволяет указать список расширений протокола SMTP, выдаваемый клиенту в ответе на команду EHLO. В зависимости от значения директивы [starttls](https://angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-starttls) к этому списку автоматически добавляются методы аутентификации, указанные в директиве [smtp_auth](#m-smtp-auth), и [STARTTLS](https://datatracker.ietf.org/doc/html/rfc3207).
В данной директиве имеет смысл указать расширения, поддерживаемые MTA, на который проксируются клиенты (если эти расширения относятся к командам, используемым после аутентификации, когда Angie прозрачно проксирует подключение клиента на бэкенд).
### smtp_client_buffer
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `smtp_client_buffer` размер; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `smtp_client_buffer 4k|8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает размер буфера для чтения SMTP-команд. По умолчанию размер одного буфера равен размеру страницы. В зависимости от платформы это или 4K, или 8K.
### smtp_greeting_delay
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `smtp_greeting_delay` размер; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `smtp_greeting_delay 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Позволяет задать задержку перед отправкой SMTP-приветствия, чтобы отклонить клиентов, не дожидающихся приветствия до начала отправки SMTP-команд.
# https://angie.software/angie/docs/configuration/modules/mail/mail_ssl.md
# SSL
Модуль обеспечивает поддержку шифрования SSL/TLS для почтовых прокси-протоколов
(POP3, IMAP, SMTP), позволяя устанавливать защищённые соединения между клиентами
и сервером. Он обеспечивает шифрование SSL/TLS для входящих подключений,
поддерживает обновление соединений через STARTTLS, управляет сертификатами и
ключами, а также контролирует настройки SSL, такие как выбор шифров и версий
протоколов.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑mail_ssl_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.
#### NOTE
Для этого модуля нужна библиотека OpenSSL.
## Пример конфигурации
Для уменьшения загрузки процессора рекомендуется
* установить число [рабочих процессов](https://angie.software//angie/docs/configuration/modules/core.md#worker-processes) равным числу процессоров,
* включить [разделяемый кэш](#m-ssl-session-cache) сессий,
* выключить [встроенный кэш](#m-ssl-session-cache) сессий
* и, возможно, увеличить [время жизни](#m-ssl-session-timeout) сессии (по умолчанию 5 минут):
```nginx
worker_processes auto;
mail {
...
server {
listen 993 ssl;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
ssl_certificate /usr/local/angie/conf/cert.pem;
ssl_certificate_key /usr/local/angie/conf/cert.key;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
# ...
}
```
## Директивы
### ssl_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_certificate` файл; |
|------------------------------------------------------------------------------------------|---------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Указывает файл с сертификатом в формате PEM для данного сервера. Если вместе с основным сертификатом нужно указать промежуточные, то они должны находиться в этом же файле в следующем порядке — сначала основной сертификат, а затем промежуточные. В этом же файле может находиться секретный ключ в формате PEM.
Директива может быть указана несколько раз для загрузки сертификатов разных типов, например RSA и ECDSA:
```nginx
server {
listen 993 ssl;
ssl_certificate example.com.rsa.crt;
ssl_certificate_key example.com.rsa.key;
ssl_certificate example.com.ecdsa.crt;
ssl_certificate_key example.com.ecdsa.key;
# ...
}
```
Возможность задавать отдельные цепочки сертификатов для разных сертификатов есть только в OpenSSL 1.0.2 и выше. Для более старых версий следует указывать только одну цепочку сертификатов.
Вместо `файла` можно указать значение "data:сертификат", при котором
сертификат загружается без использования промежуточных файлов.
Ненадлежащее использование подобного синтаксиса может быть небезопасно, например данные секретного ключа могут попасть в [лог ошибок](https://angie.software//angie/docs/configuration/modules/core.md#error-log).
### ssl_certificate_compression
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_certificate_compression` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| По умолчанию | `ssl_certificate_compression off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Разрешает сжатие TLS 1.3 [сертификатов сервера](https://datatracker.ietf.org/doc/html/rfc8879).
#### NOTE
Директива поддерживается при использовании OpenSSL версии 3.2 и выше; список поддерживаемых алгоритмов сжатия предоставляется библиотекой.
#### NOTE
Директива поддерживается при использовании [BoringSSL](https://boringssl.googlesource.com/boringssl/); список поддерживаемых алгоритмов сжатия включает `zlib`.
### ssl_certificate_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_certificate_key` файл; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Указывает файл с секретным ключом в формате PEM для данного виртуального сервера.
Вместо `файла` можно указать значение "engine:имя:id", которое загружает
ключ с указанным id из OpenSSL engine с заданным именем.
Вместо `файла` можно указать значение "store:scheme:id", которое
используется для загрузки ключа с указанным id и URI-схемой scheme,
зарегистрированной в OpenSSL provider, например [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).
Вместо `файла` также можно указать значение "data:ключ", при котором
секретный ключ загружается без использования промежуточных файлов. При этом
следует учитывать, что ненадлежащее использование подобного синтаксиса может
быть небезопасно, например данные секретного ключа могут попасть в [лог
ошибок](https://angie.software//angie/docs/configuration/modules/core.md#error-log).
### ssl_ciphers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ciphers` шифры; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `ssl_ciphers HIGH:!aNULL:!MD5;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Описывает разрешенные шифры. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL, например:
```nginx
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
```
Список шифров зависит от установленной версии OpenSSL.
Полный список можно посмотреть с помощью команды `openssl ciphers`.
#### WARNING
Директива `ssl_ciphers` *не* настраивает шифры для TLS 1.3 при
использовании OpenSSL. Для настройки шифров TLS 1.3 в OpenSSL используйте
директиву [ssl_conf_command](#m-ssl-conf-command), добавленную для расширенной
конфигурации SSL.
- В LibreSSL шифры TLS 1.3 *можно* настраивать с помощью
`ssl_ciphers`.
- В BoringSSL шифры TLS 1.3 настроить невозможно.
### ssl_client_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_client_certificate` файл; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Указывает файл с доверенными сертификатами CA в формате PEM, которые используются для [проверки](#m-ssl-verify-client) клиентских сертификатов.
Список сертификатов будет отправляться клиентам. Если это нежелательно, можно воспользоваться директивой [ssl_trusted_certificate](#m-ssl-trusted-certificate).
### ssl_conf_command
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_conf_command` имя значение; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает произвольные [конфигурационные команды](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) OpenSSL.
#### NOTE
Директива поддерживается при использовании OpenSSL 1.0.2 и выше.
Чтобы настроить шифры TLS 1.3 в OpenSSL, используйте команду `ciphersuites`.
На одном уровне может быть указано несколько директив ssl_conf_command:
```nginx
ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;
```
Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы ssl_conf_command.
#### WARNING
Изменение настроек OpenSSL напрямую может привести к неожиданному поведению.
### ssl_crl
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_crl` файл; |
|------------------------------------------------------------------------------------------|-------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Указывает файл с отозванными сертификатами (CRL) в формате PEM, используемыми для [проверки](#m-ssl-verify-client) клиентских сертификатов.
### ssl_dhparam
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_dhparam` файл; |
|------------------------------------------------------------------------------------------|-----------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Указывает файл с параметрами для DHE-шифров.
#### WARNING
По умолчанию параметры не заданы, и соответственно DHE-шифры не будут использоваться.
### ssl_ecdh_curve
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ecdh_curve` кривая; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `ssl_ecdh_curve auto;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает кривую для ECDHE-шифров.
#### NOTE
При использовании OpenSSL 1.0.2 и выше можно указывать несколько кривых, например:
```nginx
ssl_ecdh_curve prime256v1:secp384r1;
```
Специальное значение `auto` соответствует встроенному в библиотеку OpenSSL списку кривых для OpenSSL 1.0.2 и выше, или prime256v1 для более старых версий.
#### NOTE
При использовании OpenSSL 1.0.2 и выше директива задает список кривых, поддерживаемых сервером. Поэтому для работы ECDSA-сертификатов важно, чтобы список включал кривые, используемые в сертификатах.
### ssl_password_file
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_password_file` файл; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает файл с паролями от [секретных ключей](#m-ssl-certificate-key), где каждый пароль указан на отдельной строке. Пароли применяются по очереди в момент загрузки ключа.
Пример:
```nginx
mail {
ssl_password_file /etc/keys/global.pass;
...
server {
server_name mail1.example.com;
ssl_certificate_key /etc/keys/first.key;
}
server {
server_name mail2.example.com;
# вместо файла можно указать именованный канал
ssl_password_file /etc/keys/fifo;
ssl_certificate_key /etc/keys/second.key;
}
}
```
### ssl_prefer_server_ciphers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_prefer_server_ciphers` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | `ssl_prefer_server_ciphers off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
При использовании протоколов SSLv3 и TLS устанавливает приоритет серверных шифров над клиентскими.
### ssl_protocols
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`]; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| По умолчанию | `ssl_protocols TLSv1.2 TLSv1.3;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Разрешает указанные протоколы.
#### NOTE
Параметры TLSv1.1 и TLSv1.2 работают только при использовании OpenSSL 1.0.1 и выше.
Параметр TLSv1.3 работает только при использовании OpenSSL 1.1.1 и выше.
### ssl_session_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_cache` `off` | `none` | [builtin[:размер]] [shared:название:размер]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| По умолчанию | `ssl_session_cache none;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает тип и размеры кэшей для хранения параметров сессий. Тип кэша может быть следующим:
| `off` | жесткое запрещение использования кэша сессий: Angie явно сообщает клиенту, что сессии не могут использоваться повторно. |
|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `none` | мягкое запрещение использования кэша сессий: Angie сообщает клиенту, что сессии могут использоваться повторно, но на самом деле не хранит параметры сессии в кэше. |
| `builtin` | встроенный в OpenSSL кэш, используется в рамках только одного рабочего процесса. Размер кэша задается в сессиях. Если размер не задан, то он равен 20480 сессиям. Использование встроенного кэша может вести к фрагментации памяти. |
| `shared` | кэш, разделяемый между всеми рабочими процессами. Размер кэша задается в байтах, в 1 мегабайт может поместиться около 4000 сессий. У каждого разделяемого кэша должно быть произвольное название. Кэш с одинаковым названием может использоваться в нескольких серверах. Также он используется для автоматического создания, хранения и периодического обновления ключей TLS session tickets, если они не указаны явно с помощью директивы [ssl_session_ticket_key](#m-ssl-session-ticket-key). |
Можно использовать одновременно оба типа кэша, например:
```nginx
ssl_session_cache builtin:1000 shared:SSL:10m;
```
однако использование только разделяемого кэша без встроенного должно быть более эффективным.
### ssl_session_ticket_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_ticket_key` файл; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает файл с секретным ключом, применяемым при шифровании и расшифровании TLS session tickets. Директива необходима, если один и тот же ключ нужно использовать на нескольких серверах. По умолчанию используется случайно сгенерированный ключ.
Если указано несколько ключей, то только первый ключ используется для шифрования TLS session tickets. Это позволяет настроить ротацию ключей, например:
```nginx
ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;
```
Файл должен содержать 80 или 48 байт случайных данных и может быть создан следующей командой:
```console
openssl rand 80 > ticket.key
```
В зависимости от размера файла для шифрования будет использоваться либо AES256 (для 80-байтных ключей), либо AES128 (для 48-байтных ключей).
### ssl_session_tickets
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_tickets` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `ssl_session_tickets on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Разрешает или запрещает возобновление сессий при помощи [TLS session tickets](https://datatracker.ietf.org/doc/html/rfc5077).
### ssl_session_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_timeout` время; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `ssl_session_timeout 5m;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает время, в течение которого клиент может повторно использовать параметры сессии.
### ssl_trusted_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_trusted_certificate` файл; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Задает файл с доверенными сертификатами CA в формате PEM, которые используются для [проверки](#m-ssl-verify-client) клиентских сертификатов.
В отличие от [ssl_client_certificate](#m-ssl-client-certificate), список этих сертификатов не будет отправляться клиентам.
### ssl_verify_client
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_verify_client` `on` | `off` | `optional` | `optional_no_ca`; |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| По умолчанию | `ssl_verify_client off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Разрешает проверку клиентских сертификатов. Результат проверки передается в заголовке `Auth-SSL-Verify` в запросе [аутентификации](https://angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#m-auth-http). Если при проверке клиентского сертификата произошла ошибка или клиент не предоставил требуемый сертификат, соединение закрывается.
| `optional` | запрашивает клиентский сертификат, и если сертификат был предоставлен, проверяет его |
|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `optional_no_ca` | запрашивает сертификат клиента, но не требует, чтобы он был подписан доверенным сертификатом CA. Это предназначено для случаев, когда фактическая проверка сертификата осуществляется внешним по отношению к Angie сервисом. Содержимое сертификата доступно в запросах, [посылаемых](https://angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#m-auth-http-pass-client-cert) на сервер аутентификации. |
### ssl_verify_depth
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_verify_depth` число; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `ssl_verify_depth 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
Устанавливает глубину проверки в цепочке клиентских сертификатов.
### starttls
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `starttls` `on` | `off` | `only`; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `starttls off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server |
| `on` | разрешить использование команд STLS для POP3 и STARTTLS для IMAP и SMTP; |
|--------|----------------------------------------------------------------------------|
| `off` | запретить использование команд STLS и STARTTLS; |
| `only` | требовать предварительного перехода на TLS. |
# https://angie.software/angie/docs/configuration/modules/google_perftools.md
# Модуль Google PerfTools
Включает поддержку профилирования рабочих процессов Angie при помощи [Google
Performance Tools](https://github.com/gperftools/gperftools). Модуль
предназначен для разработчиков Angie и позволяет им анализировать и
оптимизировать производительность сервера, предоставляя подробную информацию об
использовании памяти, загрузке процессора и других метриках производительности.
При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild)
модуль не собирается по умолчанию;
его необходимо включить с помощью
[параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑google_perftools_module`.
#### NOTE
Для этого модуля нужна библиотека
[gperftools](https://github.com/gperftools/gperftools).
## Пример конфигурации
```nginx
google_perftools_profiles /var/log/angie/perftools;
```
Профили будут сохраняться в файлах вида
`/var/log/angie/perftools.`.
## Директивы
### google_perftools_profiles
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `google_perftools_profiles` префикс файла; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | main |
Задает префикс имени файла,
где будет храниться информация о профилировании рабочего процесса Angie.
Идентификатор рабочего процесса добавляется в конце имени через точку, например:
`/var/log/angie/perftools.1234`.
# https://angie.software/angie/docs/configuration/modules/wasm.md
# Модуль WASM
Основной модуль, реализующий базовую функциональность WASM в Angie: он включает
поддержку загрузки альтернативных сред выполнения и модулей WASM, а также
настройку их функций и ограничений.
Другие модули в этом разделе расширяют данную функциональность, позволяя гибко
настраивать и оптимизировать возможности WASM для различных сценариев и
требований.
В наших репозиториях модуль собран [динамически](https://angie.software//angie/docs/installation/index.md#install-dynamicmodules) и
доступен отдельным пакетом `angie-module-wasm`.
## Пример конфигурации
```none
# Эти директивы загружают основную функциональность
load_module modules/ngx_wasm_module.so;
load_module modules/ngx_wasm_core_module.so;
load_module modules/ngx_wasmtime_module.so;
# Доступны здесь: https://git.angie.software/web-server/angie-wasm
load_module modules/ngx_http_wasm_host_module.so;
events {
}
wasm_modules {
#use wasmtime;
load ngx_http_handler.wasm id=handler;
load ngx_http_vars.wasm id=vars type=reactor;
}
http {
wasm_var vars "ngx:wasi/var-utils#sum-entry" $rvar $arg_a $arg_b $arg_c $arg_d;
server {
listen *:8080;
location / {
return 200 "sum('$arg_a','$arg_b','$arg_c','$arg_d')=$rvar\n";
}
location /wasm {
client_max_body_size 20M;
wasm_content handler "ngx:wasi/http-handler-entry#handle-request";
}
}
}
```
## Директивы
### load
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `load` file `id=`идентификатор [`fs=`путь_хоста:путь_гостя]... [`api=`api]... [`type=``command` | `reactor`] |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | wasm_modules |
Загружает модуль из файла на диске и назначает ему уникальный идентификатор
(обязательный параметр). Во время загрузки происходит проверка того, что модуль
можно инстанцировать.
Директива поддерживает следующие параметры:
| `fs` | Позволяет гостю получить доступ к каталогу на хосте.
Параметр может быть указан несколько раз для разных каталогов. |
|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `api` | Явно ограничивает список API, разрешенных для модуля, перечисляя их.
Если модуль пытается использовать недоступные API (не указанные здесь),
возвращается ошибка "API не найден".
По умолчанию модулю доступны все API. |
| `type` | Управляет жизненным циклом загруженного модуля.
- В режиме `command` машина выполняется один раз,
и ее состояние уничтожается после выполнения.
- В режиме `reactor` машина фактически работает бесконечно,
позволяя выполнять код многократно.
Это требует внимательного управления памятью:
если ресурсы не освобождаются, могут возникнуть утечки памяти. |
### wasm_modules
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `wasm_modules` { ... }; |
|------------------------------------------------------------------------------------------|---------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | main |
Директива верхнего уровня, которая предоставляет контекст файла конфигурации,
в котором должны указываться директивы WASM.
Она может содержать команды для загрузки модулей WASM и настройки параметров,
специфичных для той или иной среды выполнения.
# https://angie.software/angie/docs/configuration/modules/wasm/wasm_wamr.md
# WAMR
Модуль обеспечивает интеграцию с [WebAssembly Micro Runtime](https://github.com/bytecodealliance/wasm-micro-runtime)
для выполнения WASM-кода,
добавляя ряд директив, специфичных для этой среды выполнения,
в контекст [wasm_modules](https://angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-modules).
В наших репозиториях модуль собран [динамически](https://angie.software//angie/docs/installation/index.md#install-dynamicmodules) и
доступен отдельным пакетом `angie-module-wamr`.
## Пример конфигурации
```nginx
wasm_modules {
wamr_heap_size 16k;
wamr_stack_size 16k;
load fft_transform.wasm id=fft;
}
```
## Директивы
### wamr_heap_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `wamr_heap_size` размер; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `wamr_heap_size 8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | wasm_modules |
Устанавливает [размер](https://angie.software//angie/docs/configuration/configfile.md#syntax) кучи для отдельного экземпляра модуля.
### wamr_global_heap_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `wamr_global_heap_size` размер; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `wamr_global_heap_size 1m;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | wasm_modules |
Устанавливает [размер](https://angie.software//angie/docs/configuration/configfile.md#syntax) кучи для всей среды выполнения WAMR.
### wamr_stack_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `wamr_stack_size` размер; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `wamr_stack_size 8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | wasm_modules |
Устанавливает [размер](https://angie.software//angie/docs/configuration/configfile.md#syntax) стека для отдельного экземпляра модуля.
# https://angie.software/angie/docs/configuration/modules/wasm/wasm_wasmtime.md
# Wasmtime
Модуль обеспечивает интеграцию со средой выполнения [Wasmtime](https://wasmtime.dev/) для выполнения WASM-кода, добавляя ряд директив,
специфичных для этой среды, в контекст [wasm_modules](https://angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-modules).
В наших репозиториях модуль собран [динамически](https://angie.software//angie/docs/installation/index.md#install-dynamicmodules) и
доступен отдельным пакетом `angie-module-wasmtime`.
## Пример конфигурации
```nginx
wasm_modules {
wasmtime_stack_size 8k;
wasmtime_enable_wasi on;
load fft_transform.wasm id=fft;
}
```
## Директивы
### wasmtime_enable_wasi
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `wasmtime_enable_wasi` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `wasmtime_enable_wasi on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | wasm_modules |
Включает или отключает использование API
[WebAssembly System Interface](https://github.com/WebAssembly/WASI),
предоставляющих базовый [POSIX-подобный функционал](https://wasi.dev/interfaces)
для WASM-модулей, запускаемых в Angie.
#### NOTE
API, специфичные для Angie, можно разрешить явно с помощью директивы
[load](https://angie.software//angie/docs/configuration/modules/wasm/index.md#load).
### wasmtime_stack_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `wasmtime_stack_size` размер; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `wasmtime_stack_size 8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | wasm_modules |
Устанавливает для значения [max_wasm_stack](https://docs.wasmtime.dev/api/wasmtime/struct.Config.html#method.max_wasm_stack)
заданный [размер](https://angie.software//angie/docs/configuration/configfile.md#syntax), тем самым ограничивая максимальный объем стека,
доступного для выполнения WASM-кода.
# https://angie.software/angie/docs/configuration/varindex.md
# Встроенные переменные
| [HTTP-модули](https://angie.software//angie/docs/configuration/modules/index.md#modules-http) | [Потоковые модули](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream) |
|----------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [$acme_cert_key_<имя>](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-key-name) | [$acme_cert_key_<имя>](https://angie.software//angie/docs/configuration/modules/stream/stream_acme.md#v-s-acme-cert-key-name) |
| [$acme_cert_<имя>](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-name) | [$acme_cert_<имя>](https://angie.software//angie/docs/configuration/modules/stream/stream_acme.md#v-s-acme-cert-name) |
| [$acme_hook_challenge](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-hook-challenge) | |
| [$acme_hook_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-hook-client) | |
| [$acme_hook_domain](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-hook-domain) | |
| [$acme_hook_keyauth](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-hook-keyauth) | |
| [$acme_hook_name](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-hook-name) | |
| [$acme_hook_token](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-hook-token) | |
| [$ancient_browser](https://angie.software//angie/docs/configuration/modules/http/http_browser.md#v-ancient-browser) | |
| [$angie_version](https://angie.software//angie/docs/configuration/modules/http/index.md#v-angie-version) | [$angie_version](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-angie-version) |
| [$arg_<имя>](https://angie.software//angie/docs/configuration/modules/http/index.md#v-arg) | |
| [$args](https://angie.software//angie/docs/configuration/modules/http/index.md#v-args) | |
| [$binary_remote_addr](https://angie.software//angie/docs/configuration/modules/http/index.md#v-binary-remote-addr) | [$binary_remote_addr](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-binary-remote-addr) |
| [$body_bytes_sent](https://angie.software//angie/docs/configuration/modules/http/index.md#v-body-bytes-sent) | |
| | [$bytes_received](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-bytes-received) |
| [$bytes_sent](https://angie.software//angie/docs/configuration/modules/http/index.md#v-bytes-sent) | [$bytes_sent](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-bytes-sent) |
| [$connection](https://angie.software//angie/docs/configuration/modules/http/index.md#v-connection) | [$connection](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-connection) |
| [$connection_requests](https://angie.software//angie/docs/configuration/modules/http/index.md#v-connection-requests) | |
| [$connection_time](https://angie.software//angie/docs/configuration/modules/http/index.md#v-connection-time) | |
| [$connections_active](https://angie.software//angie/docs/configuration/modules/http/http_stub_status.md#v-connections-active) | |
| [$connections_reading](https://angie.software//angie/docs/configuration/modules/http/http_stub_status.md#v-connections-reading) | |
| [$connections_writing](https://angie.software//angie/docs/configuration/modules/http/http_stub_status.md#v-connections-writing) | |
| [$connections_waiting](https://angie.software//angie/docs/configuration/modules/http/http_stub_status.md#v-connections-waiting) | |
| [$content_length](https://angie.software//angie/docs/configuration/modules/http/index.md#v-content-length) | |
| [$content_type](https://angie.software//angie/docs/configuration/modules/http/index.md#v-content-type) | |
| [$cookie_<имя>](https://angie.software//angie/docs/configuration/modules/http/index.md#v-cookie) | |
| [$date_local](https://angie.software//angie/docs/configuration/modules/http/http_ssi.md#v-date-local) | |
| [$date_gmt](https://angie.software//angie/docs/configuration/modules/http/http_ssi.md#v-date-gmt) | |
| [$document_root](https://angie.software//angie/docs/configuration/modules/http/index.md#v-document-root) | |
| [$document_uri](https://angie.software//angie/docs/configuration/modules/http/index.md#v-document-uri) | |
| [$fastcgi_script_name](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#v-fastcgi-script-name) | |
| [$fastcgi_path_info](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#v-fastcgi-path-info) | |
| [$gzip_ratio](https://angie.software//angie/docs/configuration/modules/http/http_gzip.md#v-gzip-ratio) | |
| [$host](https://angie.software//angie/docs/configuration/modules/http/index.md#v-host) | |
| [$hostname](https://angie.software//angie/docs/configuration/modules/http/index.md#v-hostname) | [$hostname](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-hostname) |
| [$http2](https://angie.software//angie/docs/configuration/modules/http/http_v2.md#v-http2) | |
| [$http3](https://angie.software//angie/docs/configuration/modules/http/http_v3.md#v-http3) | |
| [$http_<имя>](https://angie.software//angie/docs/configuration/modules/http/index.md#v-http) | |
| [$https](https://angie.software//angie/docs/configuration/modules/http/index.md#v-https) | |
| [$invalid_referer](https://angie.software//angie/docs/configuration/modules/http/http_referer.md#v-invalid-referer) | |
| [$is_args](https://angie.software//angie/docs/configuration/modules/http/index.md#v-is-args) | |
| [$is_request_port](https://angie.software//angie/docs/configuration/modules/http/index.md#v-is-request-port) | |
| [$limit_conn_status](https://angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#v-limit-conn-status) | [$limit_conn_status](https://angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#v-s-limit-conn-status) |
| [$limit_rate](https://angie.software//angie/docs/configuration/modules/http/index.md#v-limit-rate) | |
| [$limit_req_status](https://angie.software//angie/docs/configuration/modules/http/http_limit_req.md#v-limit-req-status) | |
| [$memcached_key](https://angie.software//angie/docs/configuration/modules/http/http_memcached.md#v-memcached-key) | |
| [$metric_](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#v-metric-zone) | |
| [$metric__key и $metric__value](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#v-metric-zone-key) | |
| [$metric__key и $metric__value](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#v-metric-zone-value) | |
| [$metric__value_](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#v-metric-zone-value-metric) | |
| [$modern_browser](https://angie.software//angie/docs/configuration/modules/http/http_browser.md#v-modern-browser) | |
| | [$mqtt_preread_clientid](https://angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#v-mqtt-preread-clientid) |
| | [$mqtt_preread_username](https://angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#v-mqtt-preread-username) |
| [$msec](https://angie.software//angie/docs/configuration/modules/http/index.md#v-msec) | [$msec](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-msec) |
| [$msie](https://angie.software//angie/docs/configuration/modules/http/http_browser.md#v-msie) | |
| [Протокол](https://angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#v-m-protocol) | |
| [$nginx_version](https://angie.software//angie/docs/configuration/modules/http/index.md#v-nginx-version) | [$nginx_version](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-nginx-version) |
| [$p8s_value](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#v-p8s-value) | |
| [$pid](https://angie.software//angie/docs/configuration/modules/http/index.md#v-pid) | [$pid](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-pid) |
| [$pipe](https://angie.software//angie/docs/configuration/modules/http/index.md#v-pipe) | |
| [$proxy_add_x_forwarded_for](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#v-proxy-add-x-forwarded-for) | |
| [$proxy_host](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#v-proxy-host) | |
| [$proxy_port](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#v-proxy-port) | |
| | [$protocol](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-protocol) |
| [$proxy_protocol_addr](https://angie.software//angie/docs/configuration/modules/http/index.md#v-proxy-protocol-addr) | [$proxy_protocol_addr](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-proxy-protocol-addr) |
| [$proxy_protocol_port](https://angie.software//angie/docs/configuration/modules/http/index.md#v-proxy-protocol-port) | [$proxy_protocol_port](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-proxy-protocol-port) |
| [$proxy_protocol_server_addr](https://angie.software//angie/docs/configuration/modules/http/index.md#v-proxy-protocol-server-addr) | [$proxy_protocol_server_addr](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-proxy-protocol-server-addr) |
| [$proxy_protocol_server_port](https://angie.software//angie/docs/configuration/modules/http/index.md#v-proxy-protocol-server-port) | [$proxy_protocol_server_port](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-proxy-protocol-server-port) |
| [$proxy_protocol_tlv_<имя>](https://angie.software//angie/docs/configuration/modules/http/index.md#v-proxy-protocol-tlv) | [$proxy_protocol_tlv_<имя>](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-proxy-protocol-tlv) |
| [$query_string](https://angie.software//angie/docs/configuration/modules/http/index.md#v-query-string) | |
| [$quic_connection](https://angie.software//angie/docs/configuration/modules/http/http_v3.md#v-quic-connection) | |
| | [$rdp_cookie](https://angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#v-rdp-cookie),
[$rdp_cookie_<имя>](https://angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#id5) |
| [$realip_remote_addr](https://angie.software//angie/docs/configuration/modules/http/http_realip.md#v-realip-remote-addr) | [$realip_remote_addr](https://angie.software//angie/docs/configuration/modules/stream/stream_realip.md#v-s-realip-remote-addr) |
| [$realip_remote_port](https://angie.software//angie/docs/configuration/modules/http/http_realip.md#v-realip-remote-port) | [$realip_remote_port](https://angie.software//angie/docs/configuration/modules/stream/stream_realip.md#v-s-realip-remote-port) |
| [$realpath_root](https://angie.software//angie/docs/configuration/modules/http/index.md#v-realpath-root) | |
| [$remote_addr](https://angie.software//angie/docs/configuration/modules/http/index.md#v-remote-addr) | [$remote_addr](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-remote-addr) |
| [$remote_port](https://angie.software//angie/docs/configuration/modules/http/index.md#v-remote-port) | [$remote_port](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-remote-port) |
| [$remote_user](https://angie.software//angie/docs/configuration/modules/http/index.md#v-remote-user) | |
| [$request](https://angie.software//angie/docs/configuration/modules/http/index.md#v-request) | |
| [$request_body](https://angie.software//angie/docs/configuration/modules/http/index.md#v-request-body) | |
| [$request_body_file](https://angie.software//angie/docs/configuration/modules/http/index.md#v-request-body-file) | |
| [$request_completion](https://angie.software//angie/docs/configuration/modules/http/index.md#v-request-completion) | |
| [$request_filename](https://angie.software//angie/docs/configuration/modules/http/index.md#v-request-filename) | |
| [$request_id](https://angie.software//angie/docs/configuration/modules/http/index.md#v-request-id) | |
| [$request_length](https://angie.software//angie/docs/configuration/modules/http/index.md#v-request-length) | |
| [$request_method](https://angie.software//angie/docs/configuration/modules/http/index.md#v-request-method) | |
| [$request_port](https://angie.software//angie/docs/configuration/modules/http/index.md#v-request-port) | |
| [$request_time](https://angie.software//angie/docs/configuration/modules/http/index.md#v-request-time) | |
| [$request_uri](https://angie.software//angie/docs/configuration/modules/http/index.md#v-request-uri) | |
| [$scheme](https://angie.software//angie/docs/configuration/modules/http/index.md#v-scheme) | |
| [$secure_link](https://angie.software//angie/docs/configuration/modules/http/http_secure_link.md#v-secure-link) | |
| [$secure_link_expires](https://angie.software//angie/docs/configuration/modules/http/http_secure_link.md#v-secure-link-expires) | |
| [$sent_http_<имя>](https://angie.software//angie/docs/configuration/modules/http/index.md#v-sent-http) | |
| [$sent_body](https://angie.software//angie/docs/configuration/modules/http/index.md#v-sent-body) | |
| [$sent_trailer_<имя>](https://angie.software//angie/docs/configuration/modules/http/index.md#v-sent-trailer) | |
| [$server_addr](https://angie.software//angie/docs/configuration/modules/http/index.md#v-server-addr) | [$server_addr](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-server-addr) |
| [$server_name](https://angie.software//angie/docs/configuration/modules/http/index.md#v-server-name) | |
| [$server_port](https://angie.software//angie/docs/configuration/modules/http/index.md#v-server-port) | [$server_port](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-server-port) |
| [$server_protocol](https://angie.software//angie/docs/configuration/modules/http/index.md#v-server-protocol) | |
| | [$session_time](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-session-time) |
| [$slice_range](https://angie.software//angie/docs/configuration/modules/http/http_slice.md#v-slice-range) | |
| [$ssl_alpn_protocol](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-alpn-protocol) | [$ssl_alpn_protocol](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-alpn-protocol) |
| [$ssl_cipher](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-cipher) | [$ssl_cipher](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-cipher) |
| [$ssl_ciphers](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-ciphers) | [$ssl_ciphers](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-ciphers) |
| [$ssl_client_escaped_cert](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-escaped-cert) | |
| | [$ssl_client_cert](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-cert) |
| [$ssl_client_fingerprint](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-fingerprint) | [$ssl_client_fingerprint](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-fingerprint) |
| [$ssl_client_i_dn](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-i-dn) | [$ssl_client_i_dn](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-i-dn) |
| [$ssl_client_i_dn_legacy](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-i-dn-legacy) | |
| [$ssl_client_raw_cert](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-raw-cert) | [$ssl_client_raw_cert](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-raw-cert) |
| [$ssl_client_s_dn](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-s-dn) | [$ssl_client_s_dn](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-s-dn) |
| [$ssl_client_s_dn_legacy](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-s-dn-legacy) | |
| [$ssl_client_serial](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-serial) | [$ssl_client_serial](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-serial) |
| [$ssl_client_sigalg](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-sigalg) | [$ssl_client_sigalg](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-sigalg) |
| [$ssl_client_v_end](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-v-end) | [$ssl_client_v_end](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-v-end) |
| [$ssl_client_v_remain](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-v-remain) | [$ssl_client_v_remain](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-v-remain) |
| [$ssl_client_v_start](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-v-start) | [$ssl_client_v_start](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-v-start) |
| [$ssl_client_verify](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-client-verify) | [$ssl_client_verify](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-client-verify) |
| [$ssl_curve](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-curve) | [$ssl_curve](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-curve) |
| [$ssl_curves](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-curves) | [$ssl_curves](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-curves) |
| [$ssl_early_data](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-early-data) | [$ssl_early_data](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-early-data) |
| [$ssl_encrypted_hello](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-encrypted-hello) | [$ssl_encrypted_hello](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-encrypted-hello) |
| | [$ssl_preread_alpn_protocols](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#v-ssl-preread-alpn-protocols) |
| | [$ssl_preread_protocol](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#v-ssl-preread-protocol) |
| | [$ssl_preread_server_name](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#v-ssl-preread-server-name) |
| [$ssl_protocol](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-protocol) | [$ssl_protocol](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-protocol) |
| [$ssl_server_name](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-server-name) | [$ssl_server_name](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-server-name) |
| [$ssl_server_cert_type](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-server-cert-type) | [$ssl_server_cert_type](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-server-cert-type) |
| [$ssl_session_id](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-session-id) | [$ssl_session_id](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-session-id) |
| [$ssl_session_reused](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-session-reused) | [$ssl_session_reused](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-session-reused) |
| [$ssl_sigalg](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-sigalg) | [$ssl_sigalg](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#v-s-ssl-sigalg) |
| [$status](https://angie.software//angie/docs/configuration/modules/http/index.md#v-status) | [$status](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-status) |
| [$sticky_sessid](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-sticky-sessid) | [$sticky_sessid](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-sticky-sessid) |
| [$sticky_sid](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-sticky-sid) | [$sticky_sid](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-sticky-sid) |
| [$time_iso8601](https://angie.software//angie/docs/configuration/modules/http/index.md#v-time-iso8601) | [$time_iso8601](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-time-iso8601) |
| [$time_local](https://angie.software//angie/docs/configuration/modules/http/index.md#v-time-local) | [$time_local](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-time-local) |
| [$tcpinfo_rtt, $tcpinfo_rttvar, $tcpinfo_snd_cwnd, $tcpinfo_rcv_space](https://angie.software//angie/docs/configuration/modules/http/index.md#v-tcpinfo) | |
| [$uid_got](https://angie.software//angie/docs/configuration/modules/http/http_userid.md#v-uid-got) | |
| [$uid_reset](https://angie.software//angie/docs/configuration/modules/http/http_userid.md#v-uid-reset) | |
| [$uid_set](https://angie.software//angie/docs/configuration/modules/http/http_userid.md#v-uid-set) | |
| [$upstream_addr](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-addr) | [$upstream_addr](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-upstream-addr) |
| [$upstream_bytes_received](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-bytes-received) | [$upstream_bytes_received](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-upstream-bytes-received) |
| [$upstream_bytes_sent](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-bytes-sent) | [$upstream_bytes_sent](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-upstream-bytes-sent) |
| [$upstream_cache_status](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-cache-status) | |
| [$upstream_cache_key](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-cache-key) | |
| [$upstream_connect_time](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-connect-time) | [$upstream_connect_time](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-upstream-connect-time) |
| [$upstream_cookie_<имя>](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-cookie) | |
| | [$upstream_first_byte_time](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-upstream-first-byte-time) |
| [$upstream_header_time](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-header-time) | |
| [$upstream_http_<имя>](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-http) | |
| [$upstream_request_method](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-request-method) | |
| [$upstream_probe (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe) | [$upstream_probe (PRO)](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#v-s-upstream-probe) |
| [$upstream_probe_body (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe-body) | |
| | [$upstream_probe_response (PRO)](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#v-s-upstream-probe-response) |
| [$upstream_response_length](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-response-length) | |
| [$upstream_response_time](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-response-time) | |
| | [$upstream_session_time](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-upstream-session-time) |
| [$upstream_status](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-status) | |
| [$upstream_sticky_status](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-sticky-status) | [$upstream_sticky_status](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-upstream-sticky-status) |
| [$upstream_trailer_<имя>](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-trailer) | |
| [$upstream_queue_time](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-queue-time) | |
| [$uri](https://angie.software//angie/docs/configuration/modules/http/index.md#v-uri) | |
# https://angie.software/angie/docs/configuration/njs-reference.md
# Справочник API NJS
Модуль [NJS](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) предоставляет объекты, методы и свойства для расширения функциональности Angie.
Данный справочник содержит только специфичные для NJS свойства, методы и модули, не соответствующие ECMAScript. Определения свойств и методов NJS, соответствующих ECMAScript, можно найти в [спецификации ECMAScript](http://www.ecma-international.org/ecma-262/).
## Объекты Angie
### HTTP-запрос
- `r.args{}`
- `r.done()`
- `r.error()`
- `r.finish()`
- `r.headersIn{}`
- `r.headersOut{}`
- `r.httpVersion`
- `r.internal`
- `r.internalRedirect()`
- `r.log()`
- `r.method`
- `r.parent`
- `r.remoteAddress`
- `r.requestBody`
- `r.requestBuffer`
- `r.requestText`
- `r.rawHeadersIn[]`
- `r.rawHeadersOut[]`
- `r.responseBody`
- `r.responseBuffer`
- `r.responseText`
- `r.return()`
- `r.send()`
- `r.sendBuffer()`
- `r.sendHeader()`
- `r.setReturnValue()`
- `r.status`
- `r.subrequest()`
- `r.uri`
- `r.rawVariables{}`
- `r.variables{}`
- `r.warn()`
Объект HTTP-запроса доступен только в модуле [HTTP JS](https://angie.software//angie/docs/installation/external-modules/http_js.md#http-js). До версии 0.8.5 все строковые свойства объекта были байтовыми строками.
`r.args{}`
> Объект аргументов запроса, только для чтения.
> Строка запроса возвращается в виде объекта. Начиная с версии 0.7.6 дублирующиеся ключи возвращаются в виде массива, ключи чувствительны к регистру, как ключи, так и значения декодируются из процентной кодировки.
> Например, строка запроса
> ```text
> a=1&b=%32&A=3&b=4&B=two%20words
> ```
> преобразуется в `r.args` следующим образом:
> ```javascript
> {a: "1", b: ["2", "4"], A: "3", B: "two words"}
> ```
> Более сложные сценарии разбора можно реализовать с помощью модуля [Query String](#njs-querystring) и переменной `$args`, например:
> ```javascript
> import qs from 'querystring';
> function args(r) {
> return qs.parse(r.variables.args);
> }
> ```
> Объект аргументов вычисляется при первом обращении к `r.args`. Если требуется только один аргумент, например `foo`, можно использовать переменные Angie:
> ```javascript
> r.variables.arg_foo
> ```
> В этом случае объект переменных Angie возвращает первое значение для заданного ключа, без учета регистра и без декодирования процентной кодировки.
> Для преобразования `r.args` обратно в строку можно использовать метод `stringify` модуля Query String.
`r.done()`
: После вызова этой функции следующие фрагменты данных будут передаваться клиенту без вызова `js_body_filter` (0.5.2). Может вызываться только из функции `js_body_filter`.
`r.error(string)`
: Записывает `string` в журнал ошибок на уровне логирования `error`.
#### NOTE
Поскольку в Angie жестко задано ограничение максимальной длины строки, в журнал может быть записано только первые 2048 байт строки.
`r.finish()`
: Завершает отправку ответа клиенту.
`r.headersIn{}`
: Объект входящих заголовков, только для чтения.
Заголовок запроса `Foo` может быть доступен с помощью синтаксиса: `headersIn.foo` или `headersIn['Foo']`.
Заголовки запроса `Authorization`, `Content-Length`, `Content-Range`, `Content-Type`, `ETag`, `Expect`, `From`, `Host`, `If-Match`, `If-Modified-Since`, `If-None-Match`, `If-Range`, `If-Unmodified-Since`, `Max-Forwards`, `Proxy-Authorization`, `Referer`, `Transfer-Encoding` и `User-Agent` могут иметь только одно значение поля (0.4.1). Дублирующиеся значения полей в заголовках `Cookie` разделяются точкой с запятой (`;`). Дублирующиеся значения полей во всех остальных заголовках запроса разделяются запятыми.
`r.headersOut{}`
: Объект исходящих заголовков для основного запроса, для записи.
Если `r.headersOut{}` является объектом ответа подзапроса, он представляет заголовки ответа. В этом случае значения полей в заголовках ответа `Accept-Ranges`, `Connection`, `Content-Disposition`, `Content-Encoding`, `Content-Length`, `Content-Range`, `Date`, `Keep-Alive`, `Server`, `Transfer-Encoding`, `X-Accel-*` могут быть опущены.
Заголовок ответа `Foo` может быть доступен с помощью синтаксиса: `headersOut.foo` или `headersOut['Foo']`.
Исходящие заголовки должны быть установлены до отправки заголовка ответа клиенту; в противном случае обновление заголовка будет проигнорировано. Это означает, что `r.headersOut{}` фактически доступен для записи в:
- обработчике `js_content` до вызова `r.sendHeader()` или `r.return()`
- обработчике `js_header_filter`
Значения полей многозначных заголовков ответа (0.4.0) могут быть установлены с помощью синтаксиса:
```javascript
r.headersOut['Foo'] = ['a', 'b']
```
где результат будет:
```text
Foo: a
Foo: b
```
Все предыдущие значения полей заголовка ответа `Foo` будут удалены.
Для стандартных заголовков ответа, которые принимают только одно значение поля, таких как `Content-Type`, будет учитываться только последний элемент массива. Значения полей заголовка ответа `Set-Cookie` всегда возвращаются в виде массива. Дублирующиеся значения полей в заголовках ответа `Age`, `Content-Encoding`, `Content-Length`, `Content-Type`, `ETag`, `Expires`, `Last-Modified`, `Location`, `Retry-After` игнорируются. Дублирующиеся значения полей во всех остальных заголовках ответа разделяются запятыми.
`r.httpVersion`
: Версия HTTP, только для чтения.
`r.internal`
: Логическое значение, `true` для внутренних location.
`r.internalRedirect(uri)`
: Выполняет внутреннее перенаправление на указанный `uri`. Если URI начинается с префикса `@`, он считается именованным location. В новом location вся обработка запроса повторяется, начиная с фазы `NGX_HTTP_SERVER_REWRITE_PHASE` для обычных location и с `NGX_HTTP_REWRITE_PHASE` для именованных location. В результате перенаправление на именованный location не проверяет ограничение `client_max_body_size`. Перенаправленные запросы становятся внутренними и могут обращаться к внутренним location. Фактическое перенаправление происходит после завершения выполнения обработчика.
#### NOTE
После перенаправления в целевом location запускается новая виртуальная машина NJS, а виртуальная машина в исходном location останавливается. Значения переменных Angie сохраняются и могут использоваться для передачи информации в целевой location. Начиная с версии 0.5.3 может использоваться переменная, объявленная с помощью директивы `js_var` для HTTP или Stream.
#### NOTE
Начиная с версии 0.7.4 метод принимает экранированные URI.
`r.log(string)`
: Записывает `string` в журнал ошибок на уровне логирования `info`.
#### NOTE
Поскольку в Angie жестко задано ограничение максимальной длины строки, в журнал может быть записано только первые 2048 байт строки.
`r.method`
: HTTP-метод, только для чтения.
`r.parent`
: Ссылка на объект родительского запроса.
`r.remoteAddress`
: Адрес клиента, только для чтения.
`r.requestBody`
: Свойство устарело в версии 0.5.0 и было удалено в версии 0.8.0. Вместо него следует использовать свойство `r.requestBuffer` или `r.requestText`.
`r.requestBuffer`
: Тело запроса клиента, если оно не было записано во временный файл (начиная с версии 0.5.0). Чтобы тело запроса клиента находилось в памяти, его размер должен быть ограничен директивой `client_max_body_size`, а размер буфера должен быть установлен с помощью `client_body_buffer_size`. Свойство доступно только в директиве `js_content`.
`r.requestText`
: То же, что и `r.requestBuffer`, но возвращает `string`. Обратите внимание, что байты, недопустимые в кодировке UTF-8, могут быть преобразованы в символ замены.
`r.rawHeadersIn[]`
: Возвращает массив пар ключ-значение точно так, как они были получены от клиента (0.4.1).
Например, при следующих заголовках запроса:
```text
Host: localhost
Foo: bar
foo: bar2
```
вывод `r.rawHeadersIn` будет:
```javascript
[
['Host', 'localhost'],
['Foo', 'bar'],
['foo', 'bar2']
]
```
Все заголовки `foo` можно собрать с помощью синтаксиса:
```javascript
r.rawHeadersIn.filter(v=>v[0].toLowerCase() == 'foo').map(v=>v[1])
```
результат будет:
```javascript
['bar', 'bar2']
```
Имена полей заголовков не преобразуются в нижний регистр, дублирующиеся значения полей не объединяются.
`r.rawHeadersOut[]`
: Возвращает массив пар ключ-значение заголовков ответа (0.4.1). Имена полей заголовков не преобразуются в нижний регистр, дублирующиеся значения полей не объединяются.
`r.responseBody`
: Свойство устарело в версии 0.5.0 и было удалено в версии 0.8.0. Вместо него следует использовать свойство `r.responseBuffer` или `r.responseText`.
`r.responseBuffer`
: Содержит тело ответа подзапроса, только для чтения (начиная с версии 0.5.0). Размер `r.responseBuffer` ограничен директивой `subrequest_output_buffer_size`.
`r.responseText`
: То же, что и `r.responseBuffer`, но возвращает строку (начиная с версии 0.5.0). Обратите внимание, что байты, недопустимые в кодировке UTF-8, могут быть преобразованы в символ замены.
`r.return(status[, string | Buffer])`
: Отправляет полный ответ с указанным `status` клиенту. Ответ может быть строкой или буфером Buffer (0.5.0).
В качестве второго аргумента можно указать либо URL перенаправления (для кодов 301, 302, 303, 307 и 308), либо текст тела ответа (для других кодов).
`r.send(string | Buffer)`
: Отправляет часть тела ответа клиенту. Отправляемые данные могут быть строкой или буфером Buffer (0.5.0).
`r.sendBuffer(data[, options])`
: Добавляет данные в цепочку фрагментов данных, которые будут переданы следующему фильтру тела (0.5.2). Фактическая передача происходит позже, когда все фрагменты данных текущей цепочки обработаны.
Данные могут быть строкой или буфером Buffer. `options` — это объект, используемый для переопределения флагов буфера Angie, полученных из буфера входящего фрагмента данных. Флаги могут быть переопределены следующими флагами:
`last`
: Логическое значение, `true`, если буфер является последним буфером.
`flush`
: Логическое значение, `true`, если буфер должен иметь флаг `flush`.
Метод может вызываться только из функции `js_body_filter`.
`r.sendHeader()`
: Отправляет HTTP-заголовки клиенту.
`r.setReturnValue(value)`
: Устанавливает возвращаемое значение обработчика `js_set` (0.7.0). В отличие от обычного оператора return, этот метод следует использовать, когда обработчик является асинхронной функцией JS. Например:
```javascript
async function js_set(r) {
const digest = await crypto.subtle.digest('SHA-256', r.headersIn.host);
r.setReturnValue(digest);
}
```
`r.status`
: Статус, для записи.
`r.subrequest(uri[, options[, callback]])`
: Создает подзапрос с заданными `uri` и `options` и устанавливает необязательный обратный вызов завершения `callback`.
Подзапрос разделяет свои входящие заголовки с клиентским запросом. Для отправки заголовков, отличных от исходных, прокси-серверу можно использовать директиву `proxy_set_header`. Для отправки совершенно нового набора заголовков прокси-серверу можно использовать директиву `proxy_pass_request_headers`.
Если `options` является строкой, она содержит строку аргументов подзапроса. В противном случае ожидается, что `options` будет объектом со следующими ключами:
`args`
: Строка аргументов, по умолчанию используется пустая строка.
`body`
: Тело запроса, по умолчанию используется тело запроса родительского объекта запроса.
`method`
: HTTP-метод, по умолчанию используется метод `GET`.
`detached`
: Логический флаг (0.3.9); если `true`, созданный подзапрос является отдельным подзапросом. Ответы на отдельные подзапросы игнорируются. В отличие от обычных подзапросов, отдельный подзапрос может быть создан внутри обработчика переменной. Флаг `detached` и аргумент callback взаимоисключающи.
Обратный вызов завершения `callback` получает объект ответа подзапроса с методами и свойствами, идентичными родительскому объекту запроса.
Начиная с версии 0.3.8, если `callback` не предоставлен, возвращается объект `Promise`, который разрешается в объект ответа подзапроса.
Например, для просмотра всех заголовков ответа в подзапросе:
```javascript
async function handler(r) {
const reply = await r.subrequest('/path');
for (const h in reply.headersOut) {
r.log(`${h}: ${reply.headersOut[h]}`);
}
r.return(200);
}
```
`r.uri`
: Текущий URI в запросе, нормализованный, только для чтения.
`r.rawVariables{}`
: Переменные Angie в виде буферов, для записи (начиная с версии 0.5.0).
`r.variables{}`
: Объект переменных Angie, для записи (начиная с версии 0.2.8).
Например, для получения переменной `$foo` можно использовать один из следующих синтаксисов:
```javascript
r.variables['foo']
r.variables.foo
```
Начиная с версии 0.8.6 к захватам регулярных выражений можно обращаться с помощью следующего синтаксиса:
```javascript
r.variables['1']
r.variables[1]
```
Angie обрабатывает переменные, на которые есть ссылки в `angie.conf`, и переменные, на которые нет ссылок, по-разному. Когда на переменную есть ссылка, она может кэшироваться, но когда на нее нет ссылки, она всегда не кэшируется. Например, когда к переменной `$request_id` обращаются только из NJS, она имеет новое значение каждый раз при вычислении. Но когда на `$request_id` есть ссылка, например:
```nginx
proxy_set_header X-Request-Id $request_id;
```
`r.variables.request_id` возвращает одно и то же значение каждый раз.
Переменная доступна для записи, если:
- она была создана с помощью директивы `js_var` для HTTP или Stream (начиная с версии 0.5.3)
- на нее есть ссылка в файле конфигурации Angie
Тем не менее, некоторым встроенным переменным все еще нельзя присвоить значение (например, `$http_`).
`r.warn(string)`
: Записывает `string` в журнал ошибок на уровне логирования `warning`.
#### NOTE
Поскольку в Angie жестко задано ограничение максимальной длины строки, в журнал может быть записано только первые 2048 байт строки.
### Stream-сессия
- `s.allow()`
- `s.decline()`
- `s.deny()`
- `s.done()`
- `s.error()`
- `s.log()`
- `s.off()`
- `s.on()`
- `s.remoteAddress`
- `s.rawVariables{}`
- `s.send()`
- `s.sendDownstream()`
- `s.sendUpstream()`
- `s.status`
- `s.setReturnValue()`
- `s.variables{}`
- `s.warn()`
Объект stream-сессии доступен только в модуле [Stream JS](https://angie.software//angie/docs/installation/external-modules/stream_js.md#stream-js). До версии 0.8.5 все строковые свойства объекта были байтовыми строками.
`s.allow()`
: Псевдоним для `s.done(0)` (0.2.4).
`s.decline()`
: Псевдоним для `s.done(-5)` (0.2.4).
`s.deny()`
: Псевдоним для `s.done(403)` (0.2.4).
`s.done([code])`
: Устанавливает код выхода `code` для обработчика текущей фазы в значение кода, по умолчанию `0`. Фактическое завершение происходит, когда обработчик js завершен и все ожидающие события, например, из `ngx.fetch()` или `setTimeout()`, обработаны (0.2.4).
Возможные значения кода:
- `0` — успешное завершение, передача управления следующей фазе
- `-5` — не определено, передача управления следующему обработчику текущей фазы (если есть)
- `403` — доступ запрещен
Может вызываться только из функции-обработчика фазы: `js_access` или `js_preread`.
`s.error(string)`
: Записывает отправленную `string` в журнал ошибок на уровне логирования `error`.
#### NOTE
Поскольку в Angie жестко задано ограничение максимальной длины строки, в журнал может быть записано только первые 2048 байт строки.
`s.log(string)`
: Записывает отправленную `string` в журнал ошибок на уровне логирования `info`.
#### NOTE
Поскольку в Angie жестко задано ограничение максимальной длины строки, в журнал может быть записано только первые 2048 байт строки.
`s.off(eventName)`
: Отменяет регистрацию обратного вызова, установленного методом `s.on()` (0.2.4).
`s.on(event, callback)`
: Регистрирует `callback` для указанного `event` (0.2.4).
`event` может быть одной из следующих строк:
`upload`
: Новые данные (строка) от клиента.
`download`
: Новые данные (строка) клиенту.
`upstream`
: Новые данные (буфер) от клиента (начиная с версии 0.5.0).
`downstream`
: Новые данные (буфер) клиенту (начиная с версии 0.5.0).
Обратный вызов завершения имеет следующий прототип: `callback(data, flags)`, где `data` — строка или буфер Buffer (в зависимости от типа события); `flags` — объект со следующими свойствами:
`last`
: Логическое значение, `true`, если data является последним буфером.
`s.remoteAddress`
: Адрес клиента, только для чтения.
`s.rawVariables`
: Переменные Angie в виде буферов, для записи (начиная с версии 0.5.0).
`s.send(data[, options])`
: Добавляет данные в цепочку фрагментов данных, которые будут переданы в прямом направлении: в обратном вызове download клиенту; в upload восходящему серверу (0.2.4). Фактическая передача происходит позже, когда все фрагменты данных текущей цепочки обработаны.
Данные могут быть строкой или буфером Buffer (0.5.0). `options` — это объект, используемый для переопределения флагов буфера Angie, полученных из буфера входящего фрагмента данных. Флаги могут быть переопределены следующими флагами:
`last`
: Логическое значение, `true`, если буфер является последним буфером.
`flush`
: Логическое значение, `true`, если буфер должен иметь флаг `flush`.
Метод может вызываться несколько раз за вызов обратного вызова.
`s.sendDownstream()`
: Идентичен `s.send()`, за исключением того, что всегда отправляет данные клиенту (начиная с версии 0.7.8).
`s.sendUpstream()`
: Идентичен `s.send()`, за исключением того, что всегда отправляет данные от клиента (начиная с версии 0.7.8).
`s.status`
: Код статуса сессии, псевдоним переменной `$status`, только для чтения (начиная с версии 0.5.2).
`s.setReturnValue(value)`
: Устанавливает возвращаемое значение обработчика `js_set` (0.7.0). В отличие от обычного оператора return, этот метод следует использовать, когда обработчик является асинхронной функцией JS. Например:
```javascript
async function js_set(r) {
const digest = await crypto.subtle.digest('SHA-256', r.headersIn.host);
r.setReturnValue(digest);
}
```
`s.variables{}`
: Объект переменных Angie, для записи (начиная с версии 0.2.8). Переменная может быть доступна для записи только в том случае, если на нее есть ссылка в файле конфигурации Angie. Тем не менее, некоторым встроенным переменным все еще нельзя присвоить значение.
`s.warn(string)`
: Записывает отправленную `string` в журнал ошибок на уровне логирования `warning`.
#### NOTE
Поскольку в Angie жестко задано ограничение максимальной длины строки, в журнал может быть записано только первые 2048 байт строки.
### Периодическая сессия
- `PeriodicSession.rawVariables{}`
- `PeriodicSession.variables{}`
Объект `Periodic Session` предоставляется в качестве первого аргумента обработчика `js_periodic` для HTTP и Stream (начиная с версии 0.8.1).
`PeriodicSession.rawVariables{}`
: Переменные Angie в виде буферов, для записи.
`PeriodicSession.variables{}`
: Объект переменных Angie, для записи.
### Заголовки
- `Headers()`
- `Headers.append()`
- `Headers.delete()`
- `Headers.get()`
- `Headers.getAll()`
- `Headers.forEach()`
- `Headers.has()`
- `Headers.set()`
Интерфейс `Headers` из API Fetch доступен начиная с версии 0.5.1.
Новый объект `Headers` можно создать с помощью конструктора `Headers()` (начиная с версии 0.7.10):
`Headers([init])`
: `init`
: Объект, содержащий HTTP-заголовки для предварительного заполнения объекта `Headers`, может быть строкой, массивом пар имя-значение или существующим объектом `Headers`.
Новый объект `Headers` можно создать со следующими свойствами и методами:
`append()`
: Добавляет новое значение в существующий заголовок в объекте `Headers` или добавляет заголовок, если он еще не существует (начиная с версии 0.7.10).
`delete()`
: Удаляет заголовок из объекта `Headers` (начиная с версии 0.7.10).
`get()`
: Возвращает строку, содержащую значения всех заголовков с указанным именем, разделенные запятой и пробелом.
`getAll(name)`
: Возвращает массив, содержащий значения всех заголовков с указанным именем.
`forEach()`
: Выполняет предоставленную функцию один раз для каждой пары ключ-значение в объекте `Headers` (начиная с версии 0.7.10).
`has()`
: Возвращает логическое значение, указывающее, существует ли заголовок с указанным именем.
`set()`
: Устанавливает новое значение для существующего заголовка в объекте `Headers` или добавляет заголовок, если он еще не существует (начиная с версии 0.7.10).
### Запрос
- `Request()`
- `Request.arrayBuffer()`
- `Request.bodyUsed`
- `Request.cache`
- `Request.credentials`
- `Request.headers`
- `Request.json()`
- `Request.method`
- `Request.mode`
- `Request.text()`
- `Request.url`
Интерфейс `Request` из API Fetch доступен начиная с версии 0.7.10.
Новый объект `Request` можно создать с помощью конструктора `Request()`:
`Request[resource[, options]])`
: Создает объект `Request` для получения данных, который может быть позже передан в `ngx.fetch()`. Аргумент `resource` может быть URL-адресом или существующим объектом `Request`. Аргумент `options` является опциональным и ожидается быть объектом со следующими ключами:
`body`
: Тело запроса, по умолчанию пусто.
`headers`
: Объект заголовков ответа — объект, содержащий HTTP-заголовки для предварительного заполнения объекта `Headers`, может быть строкой, массивом пар имя-значение или существующим объектом `Headers`.
`method`
: HTTP-метод, по умолчанию используется метод GET.
Новый объект `Request` можно создать со следующими свойствами и методами:
`arrayBuffer()`
: Возвращает `Promise`, который разрешается в `ArrayBuffer`.
`bodyUsed`
: Логическое значение, `true`, если тело было использовано в запросе.
`cache`
: Содержит режим кэширования запроса.
`credentials`
: Содержит учетные данные запроса, по умолчанию `same-origin`.
`headers`
: Объект `Headers`, доступный только для чтения, связанный с `Request`.
`json()`
: Возвращает `Promise`, который разрешается в результат анализа тела запроса как JSON.
`method`
: Содержит метод запроса.
`mode`
: Содержит режим запроса.
`text()`
: Возвращает `Promise`, который разрешается в строковое представление тела запроса.
`url`
: Содержит URL запроса.
### Ответ
- `Response()`
- `Response.arrayBuffer()`
- `Response.bodyUsed`
- `Response.headers`
- `Response.json()`
- `Response.ok`
- `Response.redirected`
- `Response.status`
- `Response.statusText`
- `Response.text()`
- `Response.type`
- `Response.url`
Интерфейс `Response` доступен начиная с версии 0.5.1.
Новый объект `Response` можно создать с помощью конструктора `Response()` (начиная с версии 0.7.10):
`Response[body[, options]])`
: Создает объект `Response`. Аргумент `body` является опциональным, может быть строкой или буфером, по умолчанию `null`. Аргумент `options` является опциональным и ожидается быть объектом со следующими ключами:
`headers`
: Объект заголовков ответа — объект, содержащий HTTP-заголовки для предварительного заполнения объекта `Headers`, может быть строкой, массивом пар имя-значение или существующим объектом `Headers`.
`status`
: Код состояния ответа.
`statusText`
: Сообщение о состоянии, соответствующее коду состояния.
Новый объект `Response()` можно создать со следующими свойствами и методами:
`arrayBuffer()`
: Берет поток `Response` и читает его до конца. Возвращает `Promise`, который разрешается в `ArrayBuffer`.
`bodyUsed`
: Логическое значение, `true`, если тело было прочитано.
`headers`
: Объект `Headers`, доступный только для чтения, связанный с `Response`.
`json()`
: Берет поток `Response` и читает его до конца. Возвращает `Promise`, который разрешается в результат анализа текста тела как JSON.
`ok`
: Логическое значение, `true`, если ответ был успешным (коды состояния между 200–299).
`redirected`
: Логическое значение, `true`, если ответ является результатом перенаправления.
`status`
: Код состояния ответа.
`statusText`
: Сообщение о состоянии, соответствующее коду состояния.
`text()`
: Берет поток `Response` и читает его до конца. Возвращает `Promise`, который разрешается в строку.
`type`
: Тип ответа.
`url`
: URL ответа.
### ngx
- `ngx.build`
- `ngx.conf_file_path`
- `ngx.conf_prefix`
- `ngx.error_log_path`
- `ngx.fetch()`
- `ngx.log()`
- `ngx.prefix`
- `ngx.version`
- `ngx.version_number`
- `ngx.worker_id`
Глобальный объект `ngx` доступен начиная с версии 0.5.0.
`ngx.build`
: Строка, содержащая опциональное имя сборки Angie, соответствует аргументу `--build=name` скрипта configure, по умолчанию `""` (0.8.0).
`ngx.conf_file_path`
: Строка, содержащая путь к файлу текущей конфигурации Angie (0.8.0).
`ngx.conf_prefix`
: Строка, содержащая путь к префиксу конфигурации Angie — каталог, в котором Angie ищет конфигурацию (0.7.8).
`ngx.error_log_path`
: Строка, содержащая путь к файлу текущего журнала ошибок (0.8.0).
`ngx.fetch(resource, [options])`
: Выполняет запрос для получения `resource` (0.5.1), который может быть URL-адресом или объектом `Request` (0.7.10). Возвращает `Promise`, который разрешается в объект `Response`. Начиная с версии 0.7.0 поддерживается схема `https://`; перенаправления не обрабатываются.
Если URL в `resource` указан как доменное имя, он определяется с помощью распознавателя. Если указана схема `https://`, директива `js_fetch_trusted_certificate` должна быть настроена для аутентификации HTTPS-сервера `resource`.
Параметр `options` ожидается быть объектом со следующими ключами:
`body`
: Тело запроса, по умолчанию пусто.
`buffer_size`
: Размер буфера для чтения ответа, по умолчанию `4096`.
`headers`
: Объект заголовков запроса.
`max_response_body_size`
: Максимальный размер тела ответа в байтах, по умолчанию `32768`.
`method`
: HTTP-метод, по умолчанию используется метод `GET`.
`verify`
: Включает или отключает проверку сертификата HTTPS-сервера, по умолчанию `true` (0.7.0).
Пример:
```javascript
let reply = await ngx.fetch('http://example.com/');
let body = await reply.text();
r.return(200, body);
```
`ngx.log(level, message)`
: Записывает сообщение в журнал ошибок с указанным уровнем логирования. Параметр `level` задает один из уровней логирования; параметр `message` может быть строкой или буфером. Можно задать следующие уровни логирования: `ngx.INFO`, `ngx.WARN` и `ngx.ERR`.
#### NOTE
Поскольку в Angie жестко задано ограничение максимальной длины строки, в журнал может быть записано только первые 2048 байт строки.
`ngx.prefix`
: Строка, содержащая путь к префиксу Angie — каталогу, который содержит файлы сервера (0.8.0).
`ngx.version`
: Строка, содержащая версию Angie, например: `1.25.0` (0.8.0).
`ngx.version_number`
: Число, содержащее номер версии Angie, например: `1025000` (0.8.0).
`ngx.worker_id`
: Число, соответствующее внутреннему идентификатору рабочего процесса Angie, значение между `0` и значением, указанным в директиве `worker_processes` (0.8.0).
### ngx.shared
Глобальный объект `ngx.shared` доступен начиная с версии 0.8.0.
#### SharedDict
- `ngx.shared.SharedDict.add()`
- `ngx.shared.SharedDict.capacity`
- `ngx.shared.SharedDict.clear()`
- `ngx.shared.SharedDict.delete()`
- `ngx.shared.SharedDict.freeSpace()`
- `ngx.shared.SharedDict.get()`
- `ngx.shared.SharedDict.has()`
- `ngx.shared.SharedDict.incr()`
- `ngx.shared.SharedDict.items()`
- `ngx.shared.SharedDict.keys()`
- `ngx.shared.SharedDict.name`
- `ngx.shared.SharedDict.pop()`
- `ngx.shared.SharedDict.replace()`
- `ngx.shared.SharedDict.set()`
- `ngx.shared.SharedDict.size()`
- `ngx.shared.SharedDict.type`
Объект общей памяти доступен начиная с версии 0.8.0. Имя общей памяти, тип и размер устанавливаются с помощью директивы `js_shared_dict_zone` в HTTP или Stream.
Объект `SharedDict()` имеет следующие свойства и методы:
`ngx.shared.SharedDict.add(key, value [,timeout])`
: Устанавливает `value` для указанного `key` в словаре только если ключ еще не существует. Аргумент `key` — это строка, представляющая ключ элемента для добавления; аргумент `value` — это значение элемента для добавления.
Опциональный аргумент `timeout` задается в миллисекундах и переопределяет параметр `timeout` директивы `js_shared_dict_zone` в HTTP или Stream (начиная с версии 0.8.5). Это может быть полезно, когда некоторые ключи ожидают иметь уникальные таймауты.
Возвращает `true`, если значение успешно добавлено в словарь `SharedDict`; `false`, если ключ уже существует в словаре. Выбрасывает `SharedMemoryError`, если в словаре `SharedDict` недостаточно свободного места. Выбрасывает `TypeError`, если значение `value` имеет другой тип, чем ожидается этот словарь.
`ngx.shared.SharedDict.capacity`
: Возвращает емкость словаря `SharedDict`, соответствует параметру `size` директивы `js_shared_dict_zone` в HTTP или Stream.
`ngx.shared.SharedDict.clear()`
: Удаляет все элементы из словаря `SharedDict`.
`ngx.shared.SharedDict.delete(key)`
: Удаляет элемент, связанный с указанным ключом, из словаря `SharedDict`; `true`, если элемент в словаре существовал и был удален, `false` иначе.
`ngx.shared.SharedDict.freeSpace()`
: Возвращает размер свободной страницы в байтах. Если размер равен нулю, словарь `SharedDict` все еще может принимать новые значения, если есть место на занятых страницах.
`ngx.shared.SharedDict.get(key)`
: Получает элемент по его `key`; возвращает значение, связанное с `key`, или `undefined`, если его нет.
`ngx.shared.SharedDict.has(key)`
: Ищет элемент по его `key`; возвращает `true`, если такой элемент существует, или `false` иначе.
`ngx.shared.SharedDict.incr(key,delta[[,init], timeout])`
: Увеличивает целое число, связанное с `key`, на `delta`. Аргумент `key` — это строка; аргумент `delta` — это число для увеличения или уменьшения значения. Если ключ не существует, элемент будет инициализирован опциональным аргументом `init`, по умолчанию `0`.
Опциональный аргумент `timeout` задается в миллисекундах и переопределяет параметр `timeout` директивы `js_shared_dict_zone` в HTTP или Stream (начиная с версии 0.8.5). Это может быть полезно, когда некоторые ключи ожидают иметь уникальные таймауты.
Возвращает новое значение. Выбрасывает `SharedMemoryError`, если в словаре `SharedDict` недостаточно свободного места. Выбрасывает `TypeError`, если этот словарь не ожидает чисел.
#### NOTE
Этот метод можно использовать только если тип словаря был объявлен с параметром `type=number` директивы `js_shared_dict_zone` в HTTP или Stream.
`ngx.shared.SharedDict.items([maxCount])`
: Возвращает массив элементов ключ-значение словаря `SharedDict` (начиная с версии 0.8.1). Параметр `maxCount` устанавливает максимальное количество элементов для получения, по умолчанию `1024`.
`ngx.shared.SharedDict.keys([maxCount])`
: Возвращает массив ключей словаря `SharedDict`. Параметр `maxCount` устанавливает максимальное количество ключей для получения, по умолчанию `1024`.
`ngx.shared.SharedDict.name`
: Возвращает имя словаря `SharedDict`, соответствует параметру `zone=` директивы `js_shared_dict_zone` в HTTP или Stream.
`ngx.shared.SharedDict.pop(key)`
: Удаляет элемент, связанный с указанным `key`, из словаря `SharedDict`; возвращает значение, связанное с `key`, или `undefined`, если его нет.
`ngx.shared.SharedDict.replace(key, value)`
: Заменяет `value` для указанного `key` только если ключ уже существует; возвращает `true`, если значение было успешно заменено, `false`, если ключ не существует в словаре `SharedDict`. Выбрасывает `SharedMemoryError`, если в словаре `SharedDict` недостаточно свободного места. Выбрасывает `TypeError`, если значение `value` имеет другой тип, чем ожидается этот словарь.
`ngx.shared.SharedDict.set(key, value [,timeout])`
: Устанавливает `value` для указанного `key`; возвращает этот словарь `SharedDict` (для связывания методов).
Опциональный аргумент `timeout` задается в миллисекундах и переопределяет параметр `timeout` директивы `js_shared_dict_zone` в HTTP или Stream (начиная с версии 0.8.5). Это может быть полезно, когда некоторые ключи ожидают иметь уникальные таймауты.
`ngx.shared.SharedDict.size()`
: Возвращает количество элементов для словаря `SharedDict`.
`ngx.shared.SharedDict.type`
: Возвращает `string` или `number`, что соответствует типу словаря `SharedDict`, установленному параметром `type=` директивы `js_shared_dict_zone` в HTTP или Stream.
## Встроенные объекты
### console
- `console.error()`
- `console.info()`
- `console.log()`
- `console.time()`
- `console.timeEnd()`
- `console.warn()`
Объект `console` доступен в Angie начиная с версии 0.8.2, в CLI начиная с версии 0.2.6.
`console.error(msg[, msg2 ...])`
: Выводит одно или несколько сообщений об ошибках. Сообщение может быть строкой или объектом.
`console.info(msg[, msg2 ...])`
: Выводит одно или несколько информационных сообщений. Сообщение может быть строкой или объектом.
`console.log(msg[, msg2 ...])`
: Выводит одно или несколько сообщений журнала. Сообщение может быть строкой или объектом.
`console.time(label)`
: Запускает таймер, который может отслеживать, сколько времени занимает операция. Параметр `label` позволяет назвать разные таймеры. Если вызывается `console.timeEnd()` с тем же именем, будет выведено время, прошедшее с начала работы таймера, в миллисекундах.
`console.timeEnd(label)`
: Останавливает таймер, ранее запущенный `console.time()`. Параметр `label` позволяет назвать разные таймеры.
`console.warn(msg[, msg2 ...])`
: Выводит одно или несколько предупреждающих сообщений. Сообщение может быть строкой или объектом.
### crypto
- `crypto.getRandomValues()`
- `crypto.subtle.encrypt()`
- `crypto.subtle.decrypt()`
- `crypto.subtle.deriveBits()`
- `crypto.subtle.deriveKey()`
- `crypto.subtle.digest()`
- `crypto.subtle.exportKey()`
- `crypto.subtle.generateKey()`
- `crypto.subtle.importKey()`
- `crypto.subtle.sign()`
- `crypto.subtle.verify()`
Объект `crypto` — это глобальный объект, который позволяет использовать криптографические функции (начиная с версии 0.7.0).
`crypto.getRandomValues(typedArray)`
: Получает криптографически надежные случайные значения. Возвращает тот же массив, переданный как `typedArray`, но с его содержимым, замененным на новые сгенерированные случайные числа. Возможные значения:
`typedArray`
: Может быть `Int8Array`, `Int16Array`, `Uint16Array`, `Int32Array` или `Uint32Array`.
`crypto.subtle.encrypt(algorithm, key, data)`
: Шифрует `data` с использованием предоставленного `algorithm` и `key`. Возвращает `Promise`, который выполняется `ArrayBuffer`, содержащим зашифрованный текст. Возможные значения:
`algorithm`
: Объект, который определяет используемый алгоритм и любые дополнительные параметры, если требуется:
- Для `RSA-OAEP` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `RSA-OAEP`:
```javascript
crypto.subtle.encrypt({name: "RSA-OAEP"}, key, data)
```
- Для `AES-CTR` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `AES-CTR`.
`counter`
: `ArrayBuffer`, `TypedArray` или `DataView` — начальное значение блока счетчика, должно быть длиной 16 байт (размер блока AES). Крайние биты длины этого блока используются для счетчика, остальные используются для nonce. Например, если length установлена на 64, то первая половина counter — это nonce, а вторая половина используется для счетчика.
`length`
: Количество битов в блоке счетчика, используемых для фактического счетчика. Счетчик должен быть достаточно большим, чтобы не переполняться.
- Для `AES-CBC` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `AES-CBC`.
`iv`
: Или вектор инициализации, это `ArrayBuffer`, `TypedArray` или `DataView`, должно быть 16 байт, непредсказуемо и предпочтительно криптографически случайно. Однако это не должно быть секретом, например, оно может быть передано в открытом виде вместе с зашифрованным текстом.
- Для `AES-GCM` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `AES-GCM`.
`iv`
: Или вектор инициализации, это `ArrayBuffer`, `TypedArray` или `DataView`, должно быть 16 байт и должно быть уникальным для каждой операции шифрования, выполняемой с заданным ключом.
`additionalData`
: (опционально) это `ArrayBuffer`, `TypedArray` или `DataView`, которое содержит дополнительные данные, которые не будут зашифрованы, но будут аутентифицированы вместе с зашифрованными данными. Если `additionalData` указан, то же данные должны быть указаны в соответствующем вызове `decrypt()`: если данные, переданные в вызов `decrypt()`, не совпадают с исходными данными, расшифровка выбросит исключение. Длина бита `additionalData` должна быть меньше `2^64 - 1`.
`tagLength`
: (опционально, по умолчанию `128`) — `number`, который определяет размер в битах тега аутентификации, сгенерированного в операции шифрования и используемого для аутентификации в соответствующем расшифровании. Возможные значения: `32`, `64`, `96`, `104`, `112`, `120` или `128`. Спецификация AES-GCM рекомендует, чтобы он был `96`, `104`, `112`, `120` или `128`, хотя `32` или `64` бита могут быть приемлемыми в некоторых приложениях.
`key`
: `CryptoKey`, которая содержит ключ, который должен быть использован для шифрования.
`data`
: `ArrayBuffer`, `TypedArray` или `DataView`, которая содержит данные для шифрования (также известные как открытый текст).
`crypto.subtle.decrypt(algorithm, key, data)`
: Расшифровывает зашифрованные данные. Возвращает `Promise` с расшифрованными данными. Возможные значения:
`algorithm`
: Объект, который определяет используемый алгоритм и любые дополнительные параметры, если требуется. Значения, указанные для дополнительных параметров, должны совпадать со значениями, переданными в соответствующий вызов `encrypt()`.
- Для `RSA-OAEP` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `RSA-OAEP`:
```javascript
crypto.subtle.encrypt({name: "RSA-OAEP"}, key, data)
```
- Для `AES-CTR` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `AES-CTR`.
`counter`
: `ArrayBuffer`, `TypedArray` или `DataView` — начальное значение блока счетчика, должно быть длиной 16 байт (размер блока AES). Крайние биты длины этого блока используются для счетчика, остальные используются для nonce. Например, если length установлена на 64, то первая половина counter — это nonce, а вторая половина используется для счетчика.
`length`
: Количество битов в блоке счетчика, используемых для фактического счетчика. Счетчик должен быть достаточно большим, чтобы не переполняться.
- Для `AES-CBC` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `AES-CBC`.
`iv`
: Или вектор инициализации, это `ArrayBuffer`, `TypedArray` или `DataView`, должно быть 16 байт, непредсказуемо и предпочтительно криптографически случайно. Однако это не должно быть секретом (например, оно может быть передано в открытом виде вместе с зашифрованным текстом).
- Для `AES-GCM` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `AES-GCM`.
`iv`
: Или вектор инициализации, это `ArrayBuffer`, `TypedArray` или `DataView`, должно быть 16 байт и должно быть уникальным для каждой операции шифрования, выполняемой с заданным ключом.
`additionalData`
: (опционально) это `ArrayBuffer`, `TypedArray` или `DataView`, которое содержит дополнительные данные, которые не будут зашифрованы, но будут аутентифицированы вместе с зашифрованными данными. Если `additionalData` указан, то же данные должны быть указаны в соответствующем вызове `decrypt()`: если данные, переданные в вызов `decrypt()`, не совпадают с исходными данными, расшифровка выбросит исключение. Длина бита `additionalData` должна быть меньше `2^64 - 1`.
`tagLength`
: (опционально, по умолчанию `128`) — `number`, который определяет размер в битах тега аутентификации, сгенерированного в операции шифрования и используемого для аутентификации в соответствующем расшифровании. Возможные значения: `32`, `64`, `96`, `104`, `112`, `120` или `128`. Спецификация AES-GCM рекомендует, чтобы он был `96`, `104`, `112`, `120` или `128`, хотя `32` или `64` бита могут быть приемлемыми в некоторых приложениях.
`key`
: `CryptoKey`, которая содержит ключ, который должен быть использован для расшифровки. Если используется `RSA-OAEP`, это свойство `privateKey` объекта `CryptoKeyPair`.
`data`
: `ArrayBuffer`, `TypedArray` или `DataView`, которая содержит данные для расшифровки (также известные как зашифрованный текст).
`crypto.subtle.deriveBits(algorithm, baseKey, length)`
: Производит массив битов из базового ключа. Возвращает `Promise`, который будет выполнен `ArrayBuffer`, содержащим производные биты. Возможные значения:
`algorithm`
: Объект, который определяет используемый алгоритм производства:
- Для `HKDF` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `HKDF`.
`hash`
: Строка с алгоритмом дайджеста для использования: `SHA-1`, `SHA-256`, `SHA-384` или `SHA-512`.
`salt`
: `ArrayBuffer`, `TypedArray` или `DataView`, который представляет случайное или псевдослучайное значение с той же длиной, что и результат функции `digest`. В отличие от входного материала ключа, передаваемого в `deriveKey()`, соль не должна держаться в секрете.
`info`
: `ArrayBuffer`, `TypedArray` или `DataView`, который представляет информацию о контексте, зависящую от приложения, используемую для привязки производного ключа к приложению или контексту и позволяющую производить различные ключи для разных контекстов при использовании одного и того же входного материала ключа. Это свойство требуется, но может быть пустым буфером.
- Для `PBKDF2` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `PBKDF2`.
`hash`
: Строка с алгоритмом дайджеста для использования: `SHA-1`, `SHA-256`, `SHA-384` или `SHA-512`.
`salt`
: `ArrayBuffer`, `TypedArray` или `DataView`, который представляет случайное или псевдослучайное значение не менее `16` байт. В отличие от входного материала ключа, передаваемого в `deriveKey()`, соль не должна держаться в секрете.
`iterations`
: `number`, который представляет количество раз, которое функция хеша будет выполнена в `deriveKey()`.
- Для `ECDH` передайте объект со следующими ключами (начиная с версии 0.9.1):
`name`
: Строка, должна быть установлена на `ECDH`.
`public`
: `CryptoKey`, который представляет открытый ключ другой стороны. Ключ должен быть сгенерирован с использованием той же кривой, что и базовый ключ.
`baseKey`
: `CryptoKey`, который представляет входные данные для алгоритма производства — исходный материал ключа для функции производства: например, для `PBKDF2` это может быть пароль, импортированный как `CryptoKey` с использованием `crypto.subtle.importKey()`.
`length`
: Число, представляющее количество битов, которые нужно производить. Для совместимости с браузером число должно быть кратно `8`.
`crypto.subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)`
: Производит секретный ключ из главного ключа. Возможные значения:
`algorithm`
: Объект, который определяет используемый алгоритм производства:
- Для `HKDF` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `HKDF`.
`hash`
: Строка с алгоритмом дайджеста для использования: `SHA-1`, `SHA-256`, `SHA-384` или `SHA-512`.
`salt`
: `ArrayBuffer`, `TypedArray` или `DataView`, который представляет случайное или псевдослучайное значение с той же длиной, что и результат функции `digest`. В отличие от входного материала ключа, передаваемого в `deriveKey()`, соль не должна держаться в секрете.
`info`
: `ArrayBuffer`, `TypedArray` или `DataView`, который представляет информацию о контексте, зависящую от приложения, используемую для привязки производного ключа к приложению или контексту и позволяющую производить различные ключи для разных контекстов при использовании одного и того же входного материала ключа. Это свойство требуется, но может быть пустым буфером.
- Для `PBKDF2` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `PBKDF2`.
`hash`
: Строка с алгоритмом дайджеста для использования: `SHA-1`, `SHA-256`, `SHA-384` или `SHA-512`.
`salt`
: `ArrayBuffer`, `TypedArray` или `DataView`, который представляет случайное или псевдослучайное значение не менее `16` байт. В отличие от входного материала ключа, передаваемого в `deriveKey()`, соль не должна держаться в секрете.
`iterations`
: `number`, который представляет количество раз, которое функция хеша будет выполнена в `deriveKey()`.
- Для `ECDH` передайте объект со следующими ключами (начиная с версии 0.9.1):
`name`
: Строка, должна быть установлена на `ECDH`.
`publicKey`
: `CryptoKey`, который представляет открытый ключ другой стороны. Ключ должен быть сгенерирован с использованием той же кривой, что и базовый ключ.
`baseKey`
: `CryptoKey`, который представляет входные данные для алгоритма производства — исходный материал ключа для функции производства: например, для `PBKDF2` это может быть пароль, импортированный как `CryptoKey` с использованием `crypto.subtle.importKey()`.
`derivedKeyAlgorithm`
: Объект, который определяет алгоритм, для которого будет использован производный ключ:
- Для `HMAC` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `HMAC`.
`hash`
: Строка с именем функции дайджеста для использования: `SHA-1`, `SHA-256`, `SHA-384` или `SHA-512`.
`length`
: (опционально) это `number`, который представляет длину в битах ключа. Если не указано, длина ключа равна размеру блока выбранной функции хеша.
- Для `AES-CTR`, `AES-CBC` или `AES-GCM` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `AES-CTR`, `AES-CBC` или `AES-GCM`, в зависимости от используемого алгоритма.
`length`
: `number`, который представляет длину в битах ключа для генерации: `128`, `192` или `256`.
`extractable`
: Логическое значение, которое указывает, будет ли возможен экспорт ключа.
`keyUsages`
: `Array`, который указывает, что можно делать с производным ключом. Использование ключей должно быть разрешено алгоритмом, установленным в `derivedKeyAlgorithm`. Возможные значения:
`encrypt`
: Ключ для шифрования сообщений.
`decrypt`
: Ключ для расшифровки сообщений.
`sign`
: Ключ для подписания сообщений.
`verify`
: Ключ для проверки подписей.
`deriveKey`
: Ключ для производства нового ключа.
`deriveBits`
: Ключ для производства битов.
`wrapKey`
: Ключ для обертывания ключа.
`unwrapKey`
: Ключ для разворачивания ключа.
`crypto.subtle.digest(algorithm, data)`
: Генерирует дайджест указанных данных. Принимает как аргументы идентификатор алгоритма дайджеста для использования и данные для дайджеста. Возвращает `Promise`, который будет выполнен дайджестом. Возможные значения:
`algorithm`
: Строка, которая определяет функцию хеша для использования: `SHA-1` (не для криптографических приложений), `SHA-256`, `SHA-384` или `SHA-512`.
`data`
: `ArrayBuffer`, `TypedArray` или `DataView`, которая содержит данные для дайджеста.
`crypto.subtle.exportKey(format, key)`
: Экспортирует ключ: принимает ключ как объект `CryptoKey` и возвращает ключ во внешнем, переносимом формате (начиная с версии 0.7.10). Если `format` был `jwk`, то `Promise` выполняется объектом JSON, содержащим ключ. В противном случае обещание выполняется `ArrayBuffer`, содержащим ключ. Возможные значения:
`format`
: Строка, которая описывает формат данных, в котором должен быть экспортирован ключ, может быть следующей:
`raw`
: Формат данных raw.
`pkcs8`
: Формат [PKCS #8](https://datatracker.ietf.org/doc/html/rfc5208).
`spki`
: Формат [SubjectPublicKeyInfo](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1).
`jwk`
: Формат [JSON Web Key](https://datatracker.ietf.org/doc/html/rfc7517) (JWK) (начиная с версии 0.7.10).
`key`
: `CryptoKey`, которая содержит ключ, который должен быть экспортирован.
`crypto.subtle.generateKey(algorithm, extractable, usage)`
: Генерирует новый ключ для симметричных алгоритмов или пару ключей для алгоритмов с открытым ключом (начиная с версии 0.7.10). Возвращает `Promise`, который выполняется сгенерированным ключом как объект `CryptoKey` или `CryptoKeyPair`. Возможные значения:
`algorithm`
: Объект словаря, который определяет тип ключа для генерации и предоставляет дополнительные параметры, специфичные для алгоритма:
- Для `RSASSA-PKCS1-v1_5`, `RSA-PSS` или `RSA-OAEP` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `RSASSA-PKCS1-v1_5`, `RSA-PSS` или `RSA-OAEP`, в зависимости от используемого алгоритма.
`hash`
: Строка, которая представляет имя функции `digest` для использования, может быть `SHA-256`, `SHA-384` или `SHA-512`.
- Для `ECDSA` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `ECDSA`.
`namedCurve`
: Строка, которая представляет имя эллиптической кривой для использования, может быть `P-256`, `P-384` или `P-521`.
- Для `HMAC` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `HMAC`.
`hash`
: Строка, которая представляет имя функции `digest` для использования, может быть `SHA-256`, `SHA-384` или `SHA-512`.
`length`
: (опционально) это число, которое представляет длину в битах ключа. Если опущено, длина ключа равна длине дайджеста, сгенерированного выбранной функцией дайджеста.
- Для `AES-CTR`, `AES-CBC` или `AES-GCM` передайте строку, определяющую алгоритм, или объект вида ` *"name": "ALGORITHM"* `, где `ALGORITHM` — это имя алгоритма.
- Для `ECDH` передайте объект со следующими ключами (начиная с версии 0.9.1):
`name`
: Строка, должна быть установлена на `ECDH`.
`namedCurve`
: Строка, которая представляет имя эллиптической кривой для использования, может быть `P-256`, `P-384` или `P-521`.
`extractable`
: Логическое значение, которое указывает, возможен ли экспорт ключа.
`usage`
: `array`, который указывает возможные действия с ключом:
`encrypt`
: Ключ для шифрования сообщений.
`decrypt`
: Ключ для расшифровки сообщений.
`sign`
: Ключ для подписания сообщений.
`verify`
: Ключ для проверки подписей.
`deriveKey`
: Ключ для производства нового ключа.
`deriveBits`
: Ключ для производства битов.
`wrapKey`
: Ключ для обертывания ключа.
`unwrapKey`
: Ключ для разворачивания ключа.
`crypto.subtle.importKey(format, keyData, algorithm, extractable, keyUsages)`
: Импортирует ключ: принимает ключ во внешнем, переносимом формате и дает объект `CryptoKey`. Возвращает `Promise`, который выполняется импортированным ключом как объект `CryptoKey`. Возможные значения:
`format`
: Строка, которая описывает формат данных ключа для импорта, может быть следующей:
`raw`
: Формат данных raw.
`pkcs8`
: Формат [PKCS #8](https://datatracker.ietf.org/doc/html/rfc5208).
`spki`
: Формат [SubjectPublicKeyInfo](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1).
`jwk`
: Формат [JSON Web Key](https://datatracker.ietf.org/doc/html/rfc7517) (JWK) (начиная с версии 0.7.10).
`keyData`
: Объект `ArrayBuffer`, `TypedArray` или `DataView`, который содержит ключ в указанном формате.
`algorithm`
: Объект словаря, который определяет тип ключа для импорта и предоставляет дополнительные параметры, специфичные для алгоритма:
- Для `RSASSA-PKCS1-v1_5`, `RSA-PSS` или `RSA-OAEP` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `RSASSA-PKCS1-v1_5`, `RSA-PSS` или `RSA-OAEP`, в зависимости от используемого алгоритма.
`hash`
: Строка, которая представляет имя функции `digest` для использования, может быть `SHA-1`, `SHA-256`, `SHA-384` или `SHA-512`.
- Для `ECDSA` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `ECDSA`.
`namedCurve`
: Строка, которая представляет имя эллиптической кривой для использования, может быть `P-256`, `P-384` или `P-521`.
- Для `HMAC` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `HMAC`.
`hash`
: Строка, которая представляет имя функции `digest` для использования, может быть `SHA-256`, `SHA-384` или `SHA-512`.
`length`
: (опционально) это число, которое представляет длину в битах ключа. Если опущено, длина ключа равна длине дайджеста, сгенерированного выбранной функцией дайджеста.
- Для `AES-CTR`, `AES-CBC` или `AES-GCM` передайте строку, определяющую алгоритм, или объект вида ` *"name": "ALGORITHM"* `, где `ALGORITHM` — это имя алгоритма.
- Для `PBKDF2` передайте строку `PBKDF2`.
- Для `HKDF` передайте строку `HKDF`.
- Для `ECDH` передайте объект со следующими ключами (начиная с версии 0.9.1):
`name`
: Строка, должна быть установлена на `ECDH`.
`namedCurve`
: Строка, которая представляет имя эллиптической кривой для использования, может быть `P-256`, `P-384` или `P-521`.
`extractable`
: Логическое значение, которое указывает, возможен ли экспорт ключа.
`keyUsages`
: `array`, который указывает возможные действия с ключом:
`encrypt`
: Ключ для шифрования сообщений.
`decrypt`
: Ключ для расшифровки сообщений.
`sign`
: Ключ для подписания сообщений.
`verify`
: Ключ для проверки подписей.
`deriveKey`
: Ключ для производства нового ключа.
`deriveBits`
: Ключ для производства битов.
`wrapKey`
: Ключ для обертывания ключа.
`unwrapKey`
: Ключ для разворачивания ключа.
`crypto.subtle.sign(algorithm, key, data)`
: Возвращает `signature` как `Promise`, который выполняется `ArrayBuffer`, содержащим подпись. Возможные значения:
`algorithm`
: Строка или объект, который определяет используемый алгоритм подписи и его параметры:
- Для `RSASSA-PKCS1-v1_5` передайте строку, определяющую алгоритм, или объект вида ` *"name": "ALGORITHM"* `.
- Для `RSA-PSS` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `RSA-PSS`.
`saltLength`
: Длинное `integer`, которое представляет длину случайной соли для использования, в байтах.
- Для `ECDSA` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `ECDSA`.
`hash`
: Идентификатор алгоритма дайджеста для использования, может быть `SHA-256`, `SHA-384` или `SHA-512`.
- Для `HMAC` передайте строку, определяющую алгоритм, или объект вида ` *"name": "ALGORITHM"* `.
`key`
: Объект `CryptoKey`, который содержит ключ для использования при подписании. Если алгоритм определяет криптосистему с открытым ключом, это закрытый ключ.
`data`
: Объект `ArrayBuffer`, `TypedArray` или `DataView`, который содержит данные для подписания.
`crypto.subtle.verify(algorithm, key, signature, data)`
: Проверяет цифровую подпись; возвращает `Promise`, который выполняется логическим значением: `true`, если подпись действительна, в противном случае `false`. Возможные значения:
`algorithm`
: Строка или объект, который определяет используемый алгоритм и его параметры:
- Для `RSASSA-PKCS1-v1_5` передайте строку, определяющую алгоритм, или объект вида ` *"name": "ALGORITHM"* `.
- Для `RSA-PSS` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `RSA-PSS`.
`saltLength`
: Длинное `integer`, которое представляет длину случайной соли для использования, в байтах.
- Для `ECDSA` передайте объект со следующими ключами:
`name`
: Строка, должна быть установлена на `ECDSA`.
`hash`
: Идентификатор алгоритма дайджеста для использования, может быть `SHA-256`, `SHA-384` или `SHA-512`.
- Для `HMAC` передайте строку, определяющую алгоритм, или объект вида ` *"name": "ALGORITHM"* `.
`key`
: Объект `CryptoKey`, который содержит ключ для использования при проверке. Это секретный ключ для симметричного алгоритма и открытый ключ для системы с открытым ключом.
`signature`
: `ArrayBuffer`, `TypedArray` или `DataView`, которая содержит подпись для проверки.
`data`
: Объект `ArrayBuffer`, `TypedArray` или `DataView`, который содержит данные, подпись которых должна быть проверена.
#### CryptoKey
- `CryptoKey.algorithm`
- `CryptoKey.extractable`
- `CryptoKey.type`
- `CryptoKey.usages`
Объект `CryptoKey` представляет криптографический `key`, полученный из одного из методов `SubtleCrypto`: `crypto.subtle.generateKey()`, `crypto.subtle.deriveKey()`, `crypto.subtle.importKey()`.
`CryptoKey.algorithm`
: Возвращает объект, описывающий алгоритм, для которого этот ключ может быть использован, и любые связанные дополнительные параметры (начиная с версии 0.8.0), только для чтения.
`CryptoKey.extractable`
: Логическое значение, `true`, если ключ может быть экспортирован (начиная с версии 0.8.0), только для чтения.
`CryptoKey.type`
: Строковое значение, которое указывает, какой вид ключа представлен объектом, только для чтения. Возможные значения:
`secret`
: Этот ключ — это секретный ключ для использования с симметричным алгоритмом.
`private`
: Этот ключ — это закрытая половина `CryptoKeyPair` асимметричного алгоритма.
`public`
: Этот ключ — это открытая половина `CryptoKeyPair` асимметричного алгоритма.
`CryptoKey.usages`
: Массив строк, указывающих, что этот ключ может быть использован для (начиная с версии 0.8.0), только для чтения. Возможные значения массива:
`encrypt`
: Ключ для шифрования сообщений.
`decrypt`
: Ключ для расшифровки сообщений.
`sign`
: Ключ для подписания сообщений.
`verify`
: Ключ для проверки подписей.
`deriveKey`
: Ключ для производства нового ключа.
`deriveBits`
: Ключ для производства битов.
#### CryptoKeyPair
- `CryptoKeyPair.privateKey`
- `CryptoKeyPair.publicKey`
`CryptoKeyPair` — это объект словаря WebCrypto API, который представляет асимметричную пару ключей.
`CryptoKeyPair.privateKey`
: Объект `CryptoKey`, который представляет закрытый ключ.
`CryptoKeyPair.publicKey`
: Объект `CryptoKey`, который представляет открытый ключ.
### njs
- `njs.version`
- `njs.version_number`
- `njs.dump()`
- `njs.memoryStats`
- `njs.on()`
Объект `njs` — это глобальный объект, представляющий текущий экземпляр VM (с версии 0.2.0).
`njs.version`
: Возвращает строку с текущей версией NJS (например, "0.7.4").
`njs.version_number`
: Возвращает число с текущей версией NJS. Например, "0.7.4" возвращается как `0x000704` (с версии 0.7.4).
`njs.dump(value)`
: Возвращает красиво отформатированное строковое представление значения.
`njs.memoryStats`
: Объект, содержащий статистику использования памяти для текущего экземпляра VM (с версии 0.7.8).
`size`
: Объем памяти в байтах, занятый пулом памяти NJS от операционной системы.
`njs.on(event, callback)`
: Регистрирует обработчик для указанного события VM (с версии 0.5.2). Событие может быть одной из следующих строк:
`exit`
: Вызывается перед уничтожением VM. Обработчик вызывается без аргументов.
### process
- `process.argv`
- `process.env`
- `process.kill()`
- `process.pid`
- `process.ppid`
Объект `process` — это глобальный объект, предоставляющий информацию о текущем процессе (0.3.3).
`process.argv`
: Возвращает массив, содержащий аргументы командной строки, переданные при запуске текущего процесса.
`process.env`
: Возвращает объект, содержащий переменные окружения пользователя.
#### NOTE
По умолчанию Angie удаляет все переменные окружения, унаследованные от родительского процесса, за исключением переменной TZ. Используйте директиву `env` для сохранения некоторых унаследованных переменных.
`process.kill(pid, number | string)`
: Отправляет сигнал процессу, идентифицируемому `pid`. Имена сигналов — это числа или строки, такие как `SIGINT` или `SIGHUP`. Дополнительную информацию см. в [kill(2)](https://man7.org/linux/man-pages/man2/kill.2.html).
`process.pid`
: Возвращает PID текущего процесса.
`process.ppid`
: Возвращает PID родительского процесса текущего процесса.
### String
По умолчанию все строки в NJS — это Unicode-строки. Они соответствуют строкам ECMAScript, содержащим символы Unicode. До версии 0.8.0 также поддерживались байтовые строки.
#### Byte Strings (Removed)
#### NOTE
Начиная с версии 0.8.0, поддержка байтовых строк и методов байтовых строк была удалена. При работе с последовательностями байтов следует использовать объект [Buffer](#njs-buffer) и свойства Buffer, такие как `r.requestBuffer`, `r.rawVariables`.
Байтовые строки содержали последовательность байтов и использовались для сериализации Unicode строк во внешние данные и десериализации из внешних источников. Например, метод `toUTF8()` сериализовал Unicode строку в байтовую строку с использованием кодировки UTF-8. Метод `toBytes()` сериализовал Unicode строку с кодовыми точками до 255 в байтовую строку; в противном случае возвращалось `null`.
Следующие методы были объявлены устаревшими и удалены в версии 0.8.0:
- `String.bytesFrom()` (удалено в 0.8.0, используйте `Buffer.from()`)
- `String.prototype.fromBytes()` (удалено в 0.8.0)
- `String.prototype.fromUTF8()` (удалено в 0.8.0, используйте `TextDecoder`)
- `String.prototype.toBytes()` (удалено в 0.8.0)
- `String.prototype.toString()` с кодировкой (удалено в 0.8.0)
- `String.prototype.toUTF8()` (удалено в 0.8.0, используйте `TextEncoder`)
## Web API
### TextDecoder
- `TextDecoder()`
- `TextDecoder.prototype.encoding`
- `TextDecoder.prototype.fatal`
- `TextDecoder.prototype.ignoreBOM`
- `TextDecoder.prototype.decode()`
`TextDecoder` создает поток кодовых точек из потока байтов (0.4.3).
`TextDecoder([[encoding], options])`
: Создает новый объект `TextDecoder` для указанной `encoding`; в настоящее время поддерживается только UTF-8. `options` — это словарь `TextDecoderOptions` со свойством:
`fatal`
: Логический флаг, указывающий, должен ли `TextDecoder.decode()` вызывать исключение `TypeError` при обнаружении ошибки кодирования, по умолчанию `false`.
`TextDecoder.prototype.encoding`
: Возвращает строку с именем кодировки, используемой `TextDecoder()`, только для чтения.
`TextDecoder.prototype.fatal`
: Логический флаг, `true` если режим ошибок является критическим, только для чтения.
`TextDecoder.prototype.ignoreBOM`
: Логический флаг, `true` если маркер порядка байтов игнорируется, только для чтения.
`TextDecoder.prototype.decode(buffer, [options])`
: Возвращает строку с текстом, декодированным из `buffer` посредством `TextDecoder()`. Буфер может быть `ArrayBuffer`. `options` — это словарь `TextDecodeOptions` со свойством:
`stream`
: Логический флаг, указывающий, будут ли следующие данные в последующих вызовах `decode()`: `true` при обработке данных по частям, и `false` для последнего фрагмента или если данные не разбиты на части. По умолчанию `false`.
Пример:
```none
>> (new TextDecoder()).decode(new Uint8Array([206,177,206,178]))
\alpha\beta
```
### TextEncoder
- `TextEncoder()`
- `TextEncoder.prototype.encode()`
- `TextEncoder.prototype.encodeInto()`
Объект `TextEncoder` создает поток байтов с кодировкой UTF-8 из потока кодовых точек (0.4.3).
`TextEncoder()`
: Возвращает вновь созданный `TextEncoder`, который будет генерировать поток байтов с кодировкой UTF-8.
`TextEncoder.prototype.encode(string)`
: Кодирует `string` в `Uint8Array` с текстом в кодировке UTF-8.
`TextEncoder.prototype.encodeInto(string, uint8Array)`
: Кодирует `string` в UTF-8, помещает результат в целевой `Uint8Array` и возвращает объект словаря, показывающий ход кодирования. Объект словаря содержит двух членов:
`read`
: Количество единиц UTF-16 кодовых точек из исходной `string`, преобразованных в UTF-8.
`written`
: Количество байтов, измененных в целевом `Uint8Array`.
## Таймеры
- `clearTimeout()`
- `setTimeout()`
`clearTimeout(timeout)`
: Отменяет объект `timeout`, созданный `setTimeout()`.
`setTimeout(function, milliseconds[, argument1, argumentN])`
: Вызывает `function` после указанного количества `milliseconds`. Можно передать один или несколько опциональных `arguments` в указанную функцию. Возвращает объект `timeout`.
Пример:
```javascript
function handler(v)
{
// ...
}
t = setTimeout(handler, 12);
// ...
clearTimeout(t);
```
### Глобальные функции
- `atob()`
- `btoa()`
`atob(encodedData)`
: Декодирует строку данных, которая была закодирована с использованием кодировки `Base64`. Параметр `encodedData` — это двоичная строка, содержащая данные в кодировке Base64. Возвращает строку, содержащую декодированные данные из `encodedData`.
Подобный метод `btoa()` может использоваться для кодирования и передачи данных, которые иначе могут вызвать проблемы связи, а затем их передачи и использования метода `atob()` для повторного декодирования данных. Например, можно кодировать, передавать и декодировать управляющие символы, такие как значения ASCII от `0` до `31`.
Пример:
```javascript
const encodedData = btoa("text to encode"); // encode a string
const decodedData = atob(encodedData); // decode the string
```
`btoa(stringToEncode)`
: Создает строку ASCII в кодировке Base64 из двоичной строки. Параметр `stringToEncode` — это двоичная строка для кодирования. Возвращает строку ASCII, содержащую представление `stringToEncode` в Base64.
Метод может использоваться для кодирования данных, которые иначе могут вызвать проблемы связи, их передачи и затем использования метода `atob()` для повторного декодирования данных. Например, можно кодировать управляющие символы, такие как значения ASCII от `0` до `31`.
Пример:
```javascript
const encodedData = btoa("text to encode"); // encode a string
const decodedData = atob(encodedData); // decode the string
```
## Встроенные модули
### Buffer
Объект `Buffer` — это совместимый с Node.js способ работы с двоичными данными. Из-за большого размера файла этот раздел ограничен полным списком методов Buffer.
- `Buffer.alloc()`
- `Buffer.allocUnsafe()`
- `Buffer.byteLength()`
- `Buffer.compare()`
- `Buffer.concat()`
- `Buffer.from(array)`
- `Buffer.from(arrayBuffer)`
- `Buffer.from(buffer)`
- `Buffer.from(object)`
- `Buffer.from(string)`
- `Buffer.isBuffer()`
- `Buffer.isEncoding()`
- `buffer[]`
- `buf.buffer`
- `buf.byteOffset`
- `buf.compare()`
- `buf.copy()`
- `buf.equals()`
- `buf.fill()`
- `buf.includes()`
- `buf.indexOf()`
- `buf.lastIndexOf()`
- `buf.length`
- `buf.readIntBE()`
- `buf.readIntLE()`
- `buf.readUIntBE()`
- `buf.readUIntLE()`
- `buf.readDoubleBE()`
- `buf.readDoubleLE()`
- `buf.readFloatBE()`
- `buf.readFloatLE()`
- `buf.subarray()`
- `buf.slice()`
- `buf.swap16()`
- `buf.swap32()`
- `buf.swap64()`
- `buf.toJSON()`
- `buf.toString()`
- `buf.write()`
- `buf.writeIntBE()`
- `buf.writeIntLE()`
- `buf.writeUIntBE()`
- `buf.writeUIntLE()`
- `buf.writeDoubleBE()`
- `buf.writeDoubleLE()`
- `buf.writeFloatBE()`
- `buf.writeFloatLE()`
Подробную документацию по методам Buffer см. в [документации Node.js по Buffer](https://nodejs.org/api/buffer.html).
### Crypto
Модуль Crypto предоставляет поддержку криптографической функциональности. Объект модуля Crypto импортируется с использованием `import crypto from 'crypto'`.
#### NOTE
Начиная с версии 0.7.0, расширенный API криптографии доступен как глобальный объект [crypto](#njs-builtin-crypto).
- `crypto.createHash()`
- `crypto.createHmac()`
`crypto.createHash(algorithm)`
: Создает и возвращает объект Hash, который может использоваться для генерации дайджестов хешей с использованием заданного `algorithm`. Алгоритм может быть `md5`, `sha1` и `sha256`.
`crypto.createHmac(algorithm, secret key)`
: Создает и возвращает объект HMAC, который использует заданный `algorithm` и `secret key`. Алгоритм может быть `md5`, `sha1` и `sha256`.
#### Hash
- `hash.update()`
- `hash.digest()`
`hash.update(data)`
: Обновляет содержимое хеша с заданными `data`.
`hash.digest([encoding])`
: Вычисляет дайджест всех данных, переданных с использованием `hash.update()`. Кодировка может быть `hex`, `base64` и `base64url`. Если кодировка не предоставлена, возвращается объект Buffer (0.4.4).
#### NOTE
До версии 0.4.4 вместо объекта Buffer возвращалась байтовая строка.
`hash.copy()`
: Создает копию текущего состояния хеша (с версии 0.7.12).
Пример:
```javascript
import crypto from 'crypto';
crypto.createHash('sha1').update('A').update('B').digest('base64url');
/* BtlFlCqiamG-GMPiK_GbvKjdK10 */
```
#### HMAC
- `hmac.update()`
- `hmac.digest()`
`hmac.update(data)`
: Обновляет содержимое HMAC с заданными `data`.
`hmac.digest([encoding])`
: Вычисляет дайджест HMAC всех данных, переданных с использованием `hmac.update()`. Кодировка может быть `hex`, `base64` и `base64url`. Если кодировка не предоставлена, возвращается объект Buffer (0.4.4).
#### NOTE
До версии 0.4.4 вместо объекта Buffer возвращалась байтовая строка.
### fs
Модуль `fs` предоставляет операции с файловой системой. Объект модуля импортируется с использованием `import fs from 'fs'`.
- `fs.accessSync()`
- `fs.appendFileSync()`
- `fs.mkdirSync()`
- `fs.readdirSync()`
- `fs.readFileSync()`
- `fs.realpathSync()`
- `fs.renameSync()`
- `fs.rmdirSync()`
- `fs.symlinkSync()`
- `fs.unlinkSync()`
- `fs.writeFileSync()`
- `fs.promises.readFile()`
- `fs.promises.appendFile()`
- `fs.promises.writeFile()`
- `fs.promises.readdir()`
- `fs.promises.mkdir()`
- `fs.promises.rmdir()`
- `fs.promises.rename()`
- `fs.promises.unlink()`
- `fs.promises.symlink()`
- `fs.promises.access()`
- `fs.promises.realpath()`
За более подробной документацией по методам fs обратитесь к
[документации Node.js по fs](https://nodejs.org/api/fs.html).
### Query String
Модуль Query String предоставляет методы для парсинга и форматирования строк запроса URL. Объект модуля импортируется с использованием `import qs from 'querystring'`.
- `querystring.decode()`
- `querystring.encode()`
- `querystring.escape()`
- `querystring.parse()`
- `querystring.stringify()`
- `querystring.unescape()`
`querystring.decode()`
: Псевдоним для `querystring.parse()`.
`querystring.encode()`
: Псевдоним для `querystring.stringify()`.
`querystring.escape(string)`
: Выполняет процентное кодирование URL `string` оптимизированным для требований строк запроса URL образом. Метод используется `querystring.stringify()` и не должен использоваться напрямую.
`querystring.parse(string[, separator[, equal[, options]]])`
: Парсит `string` как строку запроса URL и возвращает объект. Опциональный параметр `separator` (по умолчанию: `&`) указывает подстроку для разделения пар ключ-значение. Опциональный параметр `equal` (по умолчанию: `=`) указывает подстроку для разделения ключей и значений. Опциональный параметр `options` — это объект, который может содержать следующее свойство:
`decodeURIComponent`
: Функция, используемая при декодировании процентно-кодированных символов в строке запроса, по умолчанию: `querystring.unescape()`.
`maxKeys`
: Максимальное количество ключей для парсинга, по умолчанию: `1000`. Значение `0` удаляет ограничения на подсчет ключей.
Пример:
```javascript
>> qs.parse('foo=bar&abc=xyz&abc=123')
{
foo: 'bar',
abc: ['xyz', '123']
}
```
`querystring.stringify(object[, separator[, equal[, options]]])`
: Создает строку запроса URL из `object` путем итерации по его собственным свойствам. Опциональный параметр `separator` (по умолчанию: `&`) указывает подстроку для разделения пар ключ-значение. Опциональный параметр `equal` (по умолчанию: `=`) указывает подстроку для разделения ключей и значений. Опциональный параметр `options` — это объект, который может содержать следующее свойство:
`encodeURIComponent`
: Функция, используемая при преобразовании небезопасных для URL символов в процентное кодирование в строке запроса, по умолчанию: `querystring.escape()`.
Пример:
```javascript
>> qs.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' })
'foo=bar&baz=qux&baz=quux&corge='
```
`querystring.unescape(string)`
: Выполняет декодирование процентно-кодированных символов URL в `string`. Метод используется `querystring.parse()` и не должен использоваться напрямую.
### XML
- `xml.parse()`
- `xml.c14n()`
- `xml.exclusiveC14n()`
- `xml.serialize()`
- `xml.serializeToString()`
- `XMLDoc`
- `XMLNode`
- `XMLAttr`
Модуль XML позволяет работать с XML документами (с версии 0.7.10). Объект модуля XML импортируется с использованием `import xml from 'xml'`.
Пример:
```javascript
import xml from 'xml';
let data = `Tove Jani Tove Jani Tove ' */
c14n = dec.decode(xml.exclusiveC14n(doc.note, doc.note.to /* excluding 'to' */));
console.log(c14n) /* 'Jani
`excluding_node`
: Позволяет исключить из вывода часть документа.
`exclusiveC14n(root_node[, excluding_node[, withComments[,prefix_list]]])`
: Канонизирует `root_node` и его потомков согласно [Exclusive XML Canonicalization Version 1.0](https://www.w3.org/TR/xml-exc-c14n/).
`root_node`
: Является объектом-оберткой `XMLNode` или `XMLDoc` вокруг XML структуры.
`excluding_node`
: Позволяет исключить из вывода часть документа, соответствующую узлу и его потомкам.
`withComments`
: Логическое значение, по умолчанию `false`. Если `true`, канонизация соответствует [Exclusive XML Canonicalization Version 1.0](http://www.w3.org/2001/10/xml-exc-c14n#WithComments). Возвращает объект Buffer, содержащий канонизированный вывод.
`prefix_list`
: Опциональная строка с пробелами, разделяющими префиксы пространств имен для пространств имен, которые также должны быть включены в выход.
`serialize()`
: То же самое, что `xml.c14n()` (с версии 0.7.11).
`serializeToString()`
: То же самое, что `xml.c14n()`, за исключением того, что возвращает результат как `string` (с версии 0.7.11).
`XMLDoc`
: Объект-обертка XMLDoc вокруг XML структуры, корневой узел документа.
`doc.$root`
: Корень документа по его имени или undefined.
`doc.abc`
: Первый корневой тег, названный `abc`, как объект-обертка `XMLNode`.
`XMLNode`
: Объект-обертка XMLNode вокруг узла XML тега.
`node.abc`
: То же самое, что `node.$tag$abc`.
`node.$attr$abc`
: Значение атрибута узла `abc`, доступно для записи с версии 0.7.11.
`node.$attr$abc=xyz`
: То же самое, что `node.setAttribute('abc', xyz)` (с версии 0.7.11).
`node.$attrs`
: Объект-обертка `XMLAttr` для всех атрибутов узла.
`node.$name`
: Имя узла.
`node.$ns`
: Пространство имен узла.
`node.$parent`
: Родительский узел текущего узла.
`node.$tag$abc`
: Первый дочерний тег узла, названный `abc`, доступен для записи с версии 0.7.11.
`node.$tags`
: Массив всех дочерних тегов.
`node.$tags = [node1, node2, ...]`
: То же самое, что `node.removeChildren()`; `node.addChild(node1)`; `node.addChild(node2)` (с версии 0.7.11).
`node.$tags$abc`
: Все дочерние теги, названные `abc`, узла, доступны для записи с версии 0.7.11.
`node.$text`
: Содержимое узла, доступно для записи с версии 0.7.11.
`node.$text = 'abc'`
: То же самое, что `node.setText('abc')` (с версии 0.7.11).
`node.addChild(nd)`
: Добавляет XMLNode как дочерний узел к узлу (с версии 0.7.11). `nd` рекурсивно копируется перед добавлением к узлу.
`node.removeAllAttributes()`
: Удаляет все атрибуты узла (с версии 0.7.11).
`node.removeAttribute(attr_name)`
: Удаляет атрибут, названный `attr_name` (с версии 0.7.11).
`node.removeChildren(tag_name)`
: Удаляет все дочерние теги, названные `tag_name` (с версии 0.7.11). Если `tag_name` отсутствует, все дочерние теги удаляются.
`node.removeText()`
: Удаляет текстовое значение узла (0.7.11).
`node.setAttribute(attr_name, value)`
: Устанавливает значение для `attr_name` (с версии 0.7.11). Когда значение `null`, атрибут, названный `attr_name`, удаляется.
`node.setText(value)`
: Устанавливает текстовое значение для узла (с версии 0.7.11). Когда значение `null`, текст узла удаляется.
`XMLAttr`
: Объект-обертка XMLAttrs вокруг атрибутов узла XML.
`attr.abc`
: Значение атрибута `abc`.
### zlib
Модуль `zlib` (0.5.2) предоставляет функциональность сжатия и распаковки с использованием zlib. Объект модуля импортируется с использованием `import zlib from 'zlib'`.
- `zlib.constants`
- `zlib.deflateRawSync()`
- `zlib.deflateSync()`
- `zlib.inflateRawSync()`
- `zlib.inflateSync()`
`zlib.constants`
: Возвращает словарь констант zlib.
`zlib.deflateRawSync(data[, options])`
: Сжимает `data` с использованием алгоритма Deflate без заголовка zlib.
`zlib.deflateSync(data[, options])`
: Сжимает `data` с использованием алгоритма Deflate.
`zlib.inflateRawSync(data[, options])`
: Распаковывает `data` с использованием алгоритма Deflate без заголовка zlib.
`zlib.inflateSync(data[, options])`
: Распаковывает `data` с использованием алгоритма Deflate.
Параметр `options` — это объект, который может содержать следующие свойства:
`level`
: Уровень сжатия (по умолчанию: `zlib.constants.Z_DEFAULT_COMPRESSION`).
`memLevel`
: Указывает, сколько памяти должно быть выделено для состояния сжатия (по умолчанию: `zlib.constants.Z_DEFAULT_MEMLEVEL`).
`strategy`
: Настраивает алгоритм сжатия (по умолчанию: `zlib.constants.Z_DEFAULT_STRATEGY`).
`windowBits`
: Устанавливает размер окна (по умолчанию: `zlib.constants.Z_DEFAULT_WINDOWBITS`).
`dictionary`
: Buffer, содержащий предопределенный словарь сжатия.
`info`
: Логическое значение, если `true`, возвращает объект с буфером и движком.
`chunkSize`
: Размер блока для сжатия (по умолчанию: `zlib.constants.Z_DEFAULT_CHUNK`).
Пример:
```javascript
import zlib from 'zlib';
const deflated = zlib.deflateSync('Hello World!');
const inflated = zlib.inflateSync(deflated);
console.log(inflated.toString()); // 'Hello World!'
```
# https://angie.software/angie/docs/configuration/quickaccess.md
# Быстрый доступ к директивам и переменным Angie
Вы можете быстро открывать документацию по всем директивам и переменным Angie
без поиска на сайте с помощью сервиса коротких ссылок: [https://angie.ws/](https://angie.ws/).
Он позволяет легко находить часто используемые директивы, переменные и темы.
## Директивы HTTP и основного модуля
Директивы [основных настроек](https://angie.software//angie/docs/configuration/modules/core.md#core) и [HTTP-модулей](https://angie.software//angie/docs/configuration/modules/index.md#modules-http)
используют префикс `/h/` (сокращение от `http`).
Примеры:
- [listen](https://angie.software//angie/docs/configuration/modules/http/index.md#listen): [https://angie.ws/h/listen](https://angie.ws/h/listen)
- [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server): [https://angie.ws/h/server](https://angie.ws/h/server)
- [worker_connections](https://angie.software//angie/docs/configuration/modules/core.md#worker-connections): [https://angie.ws/h/worker_connections](https://angie.ws/h/worker_connections)
И так далее.
#### NOTE
Директива [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server) из модуля [Upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream)
доступна по адресу: [https://angie.ws/hu/server](https://angie.ws/hu/server).
### Upstream-директивы
Директивы в модуле [Upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream)
используют префикс `/hu/` (сокращение от `http upstream`). Примеры:
- [keepalive_requests](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive-requests): [https://angie.ws/hu/keepalive_requests](https://angie.ws/hu/keepalive_requests)
- [keepalive_time](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive-time): [https://angie.ws/hu/keepalive_time](https://angie.ws/hu/keepalive_time)
- [keepalive_timeout](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive-timeout): [https://angie.ws/hu/keepalive_timeout](https://angie.ws/hu/keepalive_timeout)
И так далее.
## Директивы потоковых модулей
Директивы в [потоковых модулях](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream) используют префикс `/s/`
(сокращение от `stream`):
- [listen](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-listen): [https://angie.ws/s/listen](https://angie.ws/s/listen)
- [map](https://angie.software//angie/docs/configuration/modules/stream/stream_map.md#s-map): [https://angie.ws/s/map](https://angie.ws/s/map)
- [server](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-server): [https://angie.ws/s/server](https://angie.ws/s/server)
И так далее.
#### NOTE
Директива [server](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-server) из модуля [Upstream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream)
доступна по адресу: [https://angie.ws/su/server](https://angie.ws/su/server).
### Upstream-директивы
Директивы в модуле [Upstream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream)
используют префикс `/su/` (сокращение от `stream upstream`):
- [upstream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream): [https://angie.ws/su/upstream](https://angie.ws/su/upstream)
- [server](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server): [https://angie.ws/su/server](https://angie.ws/su/server)
- [state (PRO)](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-state): [https://angie.ws/su/state](https://angie.ws/su/state)
И так далее.
## Переменные
Переменные используют ту же схему префиксов.
HTTP-переменные (префикс `/h/`):
- [$angie_version](https://angie.software//angie/docs/configuration/modules/http/index.md#v-angie-version): [https://angie.ws/h/$angie_version](https://angie.ws/h/$angie_version)
- [$upstream_status](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-status): [https://angie.ws/h/$upstream_status](https://angie.ws/h/$upstream_status)
Потоковые переменные (префикс `/s/`):
- [$angie_version](https://angie.software//angie/docs/configuration/modules/stream/index.md#v-s-angie-version): [https://angie.ws/s/$angie_version](https://angie.ws/s/$angie_version)
- [$upstream_session_time](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#v-s-upstream-session-time): [https://angie.ws/s/$upstream_session_time](https://angie.ws/s/$upstream_session_time)
Для переменных-заполнителей,
таких как `$http_` или `$cookie_`,
используйте префикс до символа подчеркивания: [https://angie.ws/h/$http](https://angie.ws/h/$http).
## Дополнительные темы
Также доступны короткие ссылки на другие темы:
- [Адрес URI для proxy_pass](https://angie.ws/proxy_pass_uri)
- [Балансировка нагрузки](https://angie.ws/load_balancing)
- [Выбор виртуального сервера](https://angie.ws/virtual_server_selection)
- [Выбор локации](https://angie.ws/pick_location)
- [Именованные локации](https://angie.ws/named_location)
- [Использование методов](https://angie.ws/methods_use)
- [Изменения конфигурации управления](https://angie.ws/control_config_change)
- [Коды ошибок SSL](https://angie.ws/ssl_error_codes)
- [Компактный сервер](https://angie.ws/compact_server)
- [Конфигурация](https://angie.ws/configure)
- [Логирование в syslog](https://angie.ws/syslog_logging)
- [Логирование отладки](https://angie.ws/debug_logging)
- [Настройка HTTPS](https://angie.ws/https_configuration)
- [Наследование](https://angie.ws/inheritance)
- [Обновление сервиса](https://angie.ws/service_upgrade)
- [Обработка запросов](https://angie.ws/request_processing)
- [Объединение сертификатов](https://angie.ws/certificate_chaining)
- [Объединенные локации](https://angie.ws/combined_locations)
- [Опции CLI во время работы](https://angie.ws/runtime_cli_options)
- [Оптимизация HTTPS](https://angie.ws/https_optimization)
- [Перенаправление локаций](https://angie.ws/location_redirect)
- [Перезагрузка конфигурационного файла](https://angie.ws/configfile_reloading)
- [Поддержка SNI (Server Name Indication)](https://angie.ws/sni)
- [Потоковые сессии](https://angie.ws/stream_sessions)
- [Проксирование](https://angie.ws/proxying)
- [Проксирование WebSocket](https://angie.ws/websocket_proxy)
- [Протокол HTTPS с разными IP-адресами](https://angie.ws/https_separate_ips)
- [Пути](https://angie.ws/paths)
- [Ротация логов](https://angie.ws/log_rotation)
- [Сессии по HTTP](https://angie.ws/http_sessions)
- [Сигналы управления](https://angie.ws/control_signals)
- [Синтаксис](https://angie.ws/syntax)
- [Фиктивный сервер](https://angie.ws/dummy_server)
- [Функции сборки из исходников](https://angie.ws/sourcebuild_features)
- [Хеши конфигурации](https://angie.ws/configure_hashes)
- [Циклический буфер памяти](https://angie.ws/cyclic_memory_buffer)
# https://angie.software/angie/docs/configuration/migration.md
# Миграция с nginx на Angie
Если вы переходите с nginx на Angie, поздравляем!
У нас есть руководство для вас.
Имейте в виду, что оно предназначено для базового сценария замены,
который полагается на пакетную версию Angie.
Если вы работаете с [контейнерами](https://angie.software//angie/docs/installation/docker.md#docker-images),
виртуальными машинами, нестандартными путями или
[модулями](https://angie.software//angie/docs/installation/index.md#install-dynamicmodules),
вам потребуется дополнительная подстройка.
## Установка Angie
Рекомендуем использовать официальные пакеты
из [наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages);
см. шаги по установке Angie для вашего дистрибутива.
Пока не запускайте сервер;
вместо этого проверьте его командой **sudo angie -V**:
```console
$ sudo angie -V
Angie version: Angie/|version|
nginx version: nginx/|nginxversion|
built by gcc 11.4.0
configure arguments: --prefix=/etc/angie --conf-path=/etc/angie/angie.conf ...
```
Как следует отсюда,
[конфигурация](https://angie.software//angie/docs/configuration/configfile.md#configfile)
находится в `/etc/angie/`,
когда Angie устанавливается из пакета.
## Обновление конфигурации Angie
Angie обычно требует минимальных изменений в существующей конфигурации nginx.
1. Скопируйте конфигурацию nginx в `/etc/angie/` целиком:
```console
$ sudo rsync -a --no-links /etc/nginx/ /etc/angie/
```
Предположим, конфигурация nginx хранится в `/etc/nginx/`;
измените шаги, если у вас другой путь.
2. Переименуйте основной файл конфигурации так, как ожидает Angie:
```console
$ sudo mv /etc/angie/nginx.conf /etc/angie/angie.conf
```
3. Поправьте пути во всей конфигурации Angie,
начиная с основного файла конфигурации.
Детали зависят от того, как был установлен nginx,
но, по крайней мере, необходимо обновить следующее.
Любые пути [include](https://angie.software//angie/docs/configuration/modules/core.md#include), которые пока указывают на `/etc/nginx/`:
```nginx
# include /etc/nginx/conf.d/*.conf;
# include /etc/nginx/default.d/*.conf;
# include /etc/nginx/http.d/*.conf;
# include /etc/nginx/stream.d/*.conf;
include /etc/angie/conf.d/*.conf;
include /etc/angie/default.d/*.conf;
include /etc/angie/http.d/*.conf;
include /etc/angie/stream.d/*.conf;
# include /etc/nginx/sites-enabled/*;
include /etc/angie/sites-enabled/*;
# include /etc/nginx/modules-enabled/*;
include /etc/angie/modules-enabled/*;
# include /etc/nginx/mime.types;
include /etc/angie/mime.types;
```
Файл [PID](https://angie.software//angie/docs/configuration/modules/core.md#pid), который важен для управления процессами Angie:
```nginx
# pid /var/run/nginx.pid;
# -- или --
# pid /run/nginx.pid;
pid /run/angie.pid;
```
Наконец,
[журнал обращений](https://angie.software//angie/docs/configuration/modules/http/http_log.md#access-log) и [журнал ошибок](https://angie.software//angie/docs/configuration/modules/core.md#error-log):
```nginx
# access_log /var/log/nginx/access.log;
access_log /var/log/angie/access.log;
# error_log /var/log/nginx/error.log;
error_log /var/log/angie/error.log;
```
### Виртуальные хосты
Если для включения виртуальных хостов используется директория
`sites-enabled/`, поправьте и ее:
```nginx
# include /etc/nginx/sites-enabled/*;
include /etc/angie/sites-enabled/*;
```
Затем воссоздайте символические ссылки в `/etc/angie/sites-enabled/`,
чтобы все работало.
Перечислите исходные файлы виртуальных хостов, например:
```console
$ ls -l /etc/nginx/sites-enabled/
default -> /etc/nginx/sites-available/default
```
Обратите внимание на их фактическое расположение;
здесь это `/etc/nginx/sites-available/`.
Если вы не копировали их ранее в `/etc/angie/`,
скопируйте сейчас:
```console
$ sudo rsync -a /etc/nginx/sites-available/ /etc/angie/sites-available/
```
Наконец, воссоздайте каждую символическую ссылку:
```console
$ sudo ln -s /etc/angie/sites-available/default \
/etc/angie/sites-enabled/default
```
### Динамические модули
Найдите и [установите](https://angie.software//angie/docs/installation/index.md#install-dynamicmodules)
используемые в Angie аналоги для всех динамических модулей,
упомянутых в конфигурации nginx, например:
```console
$ sudo nginx -T | grep load_module
load_module modules/ngx_http_geoip2_module.so;
load_module modules/ngx_stream_geoip2_module.so;
...
```
Это означает, что вам нужно установить пакет `angie-module-geoip2`,
и так далее.
Есть два популярных способа включения конфигурации динамических модулей:
`/usr/share/nginx/modules/`
Если динамические модули включены через `/usr/share/nginx/modules/`,
поправьте путь:
```nginx
# Load dynamic modules. See /usr/share/doc/nginx/README.dynamic.
# include /usr/share/nginx/modules/*.conf;
include /usr/share/angie/modules/*.conf;
```
Затем скопируйте файлы конфигурации модулей:
```console
$ sudo rsync -a /usr/share/nginx/modules/ /usr/share/angie/modules/
```
Наконец, измените путь [load_module](https://angie.software//angie/docs/configuration/modules/core.md#load-module) в каждом файле:
```nginx
# load_module "/usr/lib64/nginx/modules/ngx_http_geoip2_module.so";
load_module "/usr/lib64/angie/modules/ngx_http_geoip2_module.so";
```
`/etc/nginx/modules-enabled/`
Если динамические модули включены через
`/etc/nginx/modules-enabled/`,
поправьте путь:
```nginx
# include /etc/nginx/modules-enabled/*.conf;
include /etc/angie/modules-enabled/*.conf;
```
Затем воссоздайте символические ссылки в `/etc/angie/modules-enabled/`,
чтобы все работало.
Перечислите исходные файлы конфигурации модулей, например:
```console
$ ls -l /etc/nginx/modules-enabled/
mod-http-geoip2.conf -> /usr/share/nginx/modules-available/mod-http-geoip2.conf
```
Обратите внимание на их фактическое расположение;
здесь это `/usr/share/nginx/modules-available/`.
Скопируйте их в `/usr/share/angie/`:
```console
$ sudo rsync -a /usr/share/nginx/modules-available/ /usr/share/angie/modules-available/
```
Наконец, воссоздайте каждую символическую ссылку:
```console
$ sudo ln -s /usr/share/angie/modules-available/mod-http-geoip2.conf \
/etc/angie/modules-enabled/mod-http-geoip2.conf
```
### Корневая директория (необязательно)
Если [root](https://angie.software//angie/docs/configuration/modules/http/index.md#root) указывает на директорию
`/usr/share/nginx/html/`,
можно изменить директиву, указав на Angie.
Скопируйте директорию и исправьте значение `root` в конфигурации Angie:
```console
$ sudo rsync -a /usr/share/nginx/html/ /usr/share/angie/html/
```
```nginx
# root /usr/share/nginx/html;
root /usr/share/angie/html;
```
### Пользователь и группа (необязательно)
Хотя директиву [user](https://angie.software//angie/docs/configuration/modules/core.md#user) достаточно оставить как есть,
для гибкости можно использовать учетные записи Angie.
Поправьте настройки `user` в конфигурации Angie:
```nginx
# user www-data www-data;
user angie angie;
```
Измените владельца *всех* файлов конфигурации,
включая файлы в `/usr/share/angie/`,
например:
```console
$ sudo chown -R angie:angie /etc/angie/
$ sudo chown -R angie:angie /usr/share/angie/
```
Если в конфигурации Angie есть директивы [root](https://angie.software//angie/docs/configuration/modules/http/index.md#root),
измените владельца указанных там директорий,
например:
```console
$ sudo chown -R angie:angie /var/www/html/
```
### Завершение
Чтобы ничего не пропустить,
найдите и исправьте оставшиеся упоминания `nginx` в конфигурации Angie:
```console
$ grep -rn --include='*.conf' 'nginx' /etc/angie/
```
## Тестирование и переключение
Обновив конфигурацию Angie,
следующим шагом проверьте ее синтаксис,
чтобы убедиться, что Angie может с ней работать,
а затем переключиться.
Проверьте, что Angie воспринимает новую конфигурацию:
```console
$ sudo angie -t
```
Эта команда анализирует конфигурацию
и сообщает об ошибках, которые блокируют запуск Angie;
исправьте все проблемы и перезапустите команду.
### Остановка nginx, запуск Angie
Чтобы минимизировать простой, запустите Angie сразу после остановки nginx:
```console
$ sudo systemctl stop nginx && sudo systemctl start angie
```
При необходимости включите службу Angie для запуска после перезагрузки:
```console
$ sudo systemctl enable angie
```
Миграция завершена! На этом все; вы великолепны.
### Отключение nginx
Убедившись, что Angie работает стабильно,
можно отключить или удалить nginx, чтобы избежать конфликтов.
Минимум того, что вы можете сделать, — это отключить службу:
```console
$ sudo systemctl disable nginx
```
## Работа с SSL-сертификатами
Если вы использовали Certbot для управления SSL-сертификатами с nginx,
он продолжит работать и с Angie.
### Использование Certbot с Angie
Поддержка Angie в Certbot требует минимальных усилий,
поскольку Angie обратно совместим с nginx.
Для работы Certbot достаточно создать символическую ссылку
и указать соответствующие параметры:
```console
# Создание символической ссылки для совместимости с Certbot
$ sudo ln -s /etc/angie/angie.conf /etc/angie/nginx.conf
# Получение сертификата для домена
$ sudo certbot --nginx --nginx-server-root=/etc/angie --nginx-ctl=angie -d example.com -d www.example.com
# Автоматическое обновление сертификатов
$ sudo certbot renew
# Проверка статуса сертификатов
$ sudo certbot certificates
```
После миграции на Angie Certbot продолжит автоматически обновлять сертификаты
через настроенные задачи **cron** или таймеры **systemd**.
### Миграция с Certbot на встроенный модуль ACME
Angie включает встроенный [модуль ACME](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme),
который позволяет автоматически получать и обновлять SSL-сертификаты
без использования внешних инструментов, таких как Certbot.
Преимущества встроенного модуля ACME:
- полная интеграция с конфигурацией Angie;
- автоматическое обновление сертификатов без дополнительных служб;
- поддержка HTTP- и DNS-проверки;
- возможность получения wildcard-сертификатов.
Подробные инструкции по переходу с Certbot на встроенный модуль ACME
см. в разделе [Миграция с certbot](https://angie.software//angie/docs/configuration/acme.md#acme-config-certbot).
## Адаптация изменившихся директив
Некоторые директивы nginx ведут себя в Angie иначе: одни переименованы, другие
объявлены устаревшими, а несколько опущены полностью. Если ваша конфигурация
использует какие-либо из них, см. [Неподдерживаемые директивы nginx](https://angie.software//angie/docs/configuration/nginx-unsupported-directives.md#nginx-unsupported-directives).
В частности, директива nginx `keepalive_min_timeout` в Angie называется
[lingering_timeout](https://angie.software//angie/docs/configuration/modules/http/index.md#lingering-timeout); переименуйте её, если она встречается в вашей
конфигурации.
## Настройка функций Angie
Можно предположить, что миграция нужна вам не просто так.
Почему бы не пойти дальше и не настроить некоторые из дополнительных функций,
которые есть в [Angie](https://angie.software//angie/docs/oss_changes.md#oss-changes) и [Angie PRO](https://angie.software//angie/docs/pro_changes.md#pro-changes),
но нет в nginx?
# https://angie.software/angie/docs/configuration/acme.md
# Настройка ACME
Модуль [ACME](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) в Angie
обеспечивает автоматическое получение сертификатов с использованием [протокола
ACME](https://datatracker.ietf.org/doc/html/rfc8555).
Протокол ACME предусматривает несколько способов проверки доменов
(также используется термин верификация);
модуль реализует
[HTTP-проверку](#acme-config-http), [DNS-проверку](#acme-config-dns),
[ALPN-проверку](#acme-config-alpn), а также
[проверку с помощью хуков](#acme-config-hooks)
через самостоятельно реализуемый внешний сервис.
## Шаги настройки
Общие шаги для включения запроса сертификатов в конфигурации:
- **Настройте ACME-клиент** в блоке `http`
с помощью директивы [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client),
задающей уникальное имя клиента и другие параметры;
можно настроить несколько клиентов ACME.
- **Укажите домены, для которых запрашиваются сертификаты**:
для доменных имен, перечисленных во всех директивах [server_name](https://angie.software//angie/docs/configuration/modules/http/index.md#server-name)
всех блоков `server` с директивами [acme](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#id4),
указывающими на один и тот же ACME-клиент,
будет выдан единый сертификат.
- **Настройте обработку запросов и вызовов ACME**:
это нужно для проверки владения доменом.
Способ настройки зависит от способа проверки доменных имен:
| Способ | Требования к пользователю | Мультидомены | Домены со звездочкой |
|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------|------------------------|
| [HTTP-проверка](#acme-config-http) | Открыть порт 80 (или указанный в [acme_http_port](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-http-port))
для входящих соединений на сервере Angie. | ✔ | |
| [DNS-проверка](#acme-config-dns) | Открыть порт 53 (или указанный в [acme_dns_port](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-dns-port))
для входящих соединений на сервере Angie.
Настроить NS-запись для поддомена `_acme-challenge.`,
направив ее на свой сервер Angie. | ✔ | ✔ |
| [ALPN-проверка](#acme-config-alpn) | Открыть порт 443 (или TLS-порт, используемый сервером Angie)
для входящих соединений. | ✔ | |
| [Проверка хуками](#acme-config-hooks) | Реализовать внешний сервис (скрипт или приложение),
который по команде Angie сможет внести изменения в DNS-зону
или разместить специальный ответ на веб-сервере. | ✔ | ✔ |
- **Настройте SSL с использованием полученного сертификата и ключа**:
Модуль делает сертификаты и ключи доступными в виде
[встроенных переменных](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme-variables),
которые можно использовать в [конфигурации](https://angie.software//angie/docs/configuration/configfile.md#configfile)
для заполнения [ssl_certificate](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate) и [ssl_certificate_key](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate-key).
Инструкции по настройке SSL см. в разделе [Настройка SSL](https://angie.software//angie/docs/configuration/ssl.md#ssl-config).
## Подробности реализации
Здесь ключи и сертификаты клиентов хранятся
в [кодировке PEM](https://datatracker.ietf.org/doc/html/rfc7468)
в соответствующих подкаталогах каталога,
заданного с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`--http-acme-client-path`:
```console
$ ls /var/lib/angie/acme/example/
account.key certificate.pem private.key
```
#### NOTE
Эти файлы сохраняются на диске между перезапусками. При запуске клиент
повторно использует сохраненный сертификат, если тот еще действителен,
вместо запроса нового, что устраняет задержку на выпуск и лишние обращения
к серверу CA, на которые могут действовать [ограничения частоты запросов](https://letsencrypt.org/docs/rate-limits/). В контейнере размещайте
каталог хранения (по умолчанию `/var/lib/angie/acme/`) на постоянном
томе, чтобы выданные сертификаты сохранялись при пересоздании контейнера;
см. [запуск Angie в контейнере](https://angie.software//angie/docs/installation/docker.md#running).
Клиенту ACME требуется учетная запись на сервере CA.
Для ее создания и управления ею клиент использует закрытый ключ
(`account.key`);
если ключа у него еще нет, ключ создается при запуске.
Затем клиент использует его для регистрации учетной записи на сервере.
#### NOTE
Если у вас уже есть ключ учетной записи,
поместите его в подкаталог клиента перед запуском
для повторного использования учетной записи.
Файл ключа также можно указать с помощью параметра `account_key`
в [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client).
Клиент ACME также использует отдельный ключ
(`private.key`) для запросов на подпись сертификата (CSR);
если нужно, этот ключ сертификата также создается автоматически при запуске.
При запуске клиент запрашивает сертификат, если его еще нет,
подписывая и отправляя CSR для всех доменов, которыми он управляет, серверу CA.
Сервер проверяет владение доменом
путем [HTTP-](#acme-config-http) или [DNS-проверки](#acme-config-dns)
и выдает сертификат,
который клиент сохраняет локально (`certificate.pem`).
Как сказано выше, сертификат будет единым для всех доменных имен,
для которых используется один и тот же ACME-клиент,
то есть потенциально может быть мультидоменным.
Список всех имен, для которых выдан сертификат,
см. в разделе Subject Alternative Name (SAN) полученного сертификата.
Проверить его можно в командной строке, например:
```console
$ openssl x509 -in certificate.pem -noout -text | grep -A5 "Subject Alternative Name"
```
Когда приближается завершение срока действия сертификата
или изменяется список доменов,
клиент подписывает и отправляет еще один CSR на сервер CA.
Сервер снова проверяет владение и выдает новый сертификат,
который клиент устанавливает локально, заменяя предыдущий.
В [конфигурации](https://angie.software//angie/docs/configuration/configfile.md#configfile) полученный сертификат и соответствующий ключ
доступны через префиксные переменные
[$acme_cert_<имя>](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-name) и [$acme_cert_key_<имя>](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-key-name).
Их значения — содержимое соответствующих файлов,
которое следует использовать
с директивами [ssl_certificate](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate) и [ssl_certificate_key](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate-key), например:
```nginx
server {
listen 443 ssl;
server_name example.com www.example.com;
acme example;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
}
```
#### NOTE
Клиент ACME определяет адрес сервера CA по его имени через настроенный
[resolver](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver), который должен присутствовать в том же контексте. На узле
без поддержки IPv6 resolver может все равно отправлять AAAA-запросы (IPv6)
для сервера CA и не суметь подключиться; отключите их параметром
`ipv6=off`, например `resolver 127.0.0.53 ipv6=off;`.
## Сбор доменов и использование сертификата
Директива [acme](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#id4) служит только для сбора доменных имен
для запросов сертификатов.
Она не определяет, где можно использовать сертификат:
любой блок `server` может ссылаться на полученный сертификат
через переменную [$acme_cert_<имя>](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-name),
независимо от того, содержит ли блок директиву `acme`.
Например, если у вас есть блок `server` с маской,
который уже охватывает все поддомены,
дополнительные блоки `server` для конкретных поддоменов
не нуждаются в директиве `acme`:
```nginx
http {
resolver 127.0.0.53;
acme_client example https://acme-v02.api.letsencrypt.org/directory
challenge=dns;
# В этом блоке перечислены домены для запроса сертификата
server {
listen 443 ssl;
server_name example.com *.example.com;
acme example;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
}
# Этот блок использует тот же сертификат, но не добавляет
# свой server_name в запрос на сертификат
server {
listen 443 ssl;
server_name app.example.com;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
}
}
```
### Явный список доменов
Чтобы точно контролировать набор доменных имен в сертификате,
не полагаясь на автоматический сбор из всех блоков `server`,
создайте отдельный блок `server`,
содержащий только директивы [server_name](https://angie.software//angie/docs/configuration/modules/http/index.md#server-name) и [acme](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#id4).
Чтобы этот блок не обрабатывал реальный трафик,
привяжите его к Unix-сокету:
```nginx
# Отдельный блок, определяющий список доменов сертификата
server {
listen unix:/tmp/acme_example.sock;
server_name example.com www.example.com;
acme example;
}
```
Другие блоки `server` могут затем использовать сертификат
через переменную [$acme_cert_<имя>](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-name),
не влияя на то, какие домены запрашиваются.
### Отдельные сертификаты для разных доменов
Каждый [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) управляет одним сертификатом. Чтобы получить
несколько независимых сертификатов (например, для несвязанных доменов, которым
не следует использовать общий сертификат), настройте отдельный
[acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) для каждого из них в блоке `http` и укажите в директиве
[acme](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#id4) каждого блока `server` соответствующий клиент по имени:
```nginx
http {
resolver 127.0.0.53;
# Два независимых клиента, каждый управляет своим сертификатом
acme_client shop https://acme-v02.api.letsencrypt.org/directory
challenge=http;
acme_client blog https://acme-v02.api.letsencrypt.org/directory
challenge=http;
server {
listen 443 ssl;
server_name shop.example.com www.shop.example.com;
acme shop;
ssl_certificate $acme_cert_shop;
ssl_certificate_key $acme_cert_key_shop;
}
server {
listen 443 ssl;
server_name blog.example.com;
acme blog;
ssl_certificate $acme_cert_blog;
ssl_certificate_key $acme_cert_key_blog;
}
}
```
## HTTP-проверка
Проверка работает автоматически.
Суть ее заключается в том, что ACME-сервер, получив запрос,
[запрашивает у клиента через HTTP](https://datatracker.ietf.org/doc/html/rfc8555#section-8.3)
особый файл-токен по адресу `/.well-known/acme-challenge/`.
Наш модуль ACME отслеживает такие запросы и самостоятельно обрабатывает их.
Получив ожидаемый ответ с нужным содержимым,
ACME-сервер подтверждает, что домен принадлежит клиенту.
### Пример конфигурации
Здесь ACME-клиент с именем `example` управляет сертификатами для
`example.com` и `www.example.com`
(учтите, что wildcard-сертификаты не поддерживаются при HTTP-проверке):
```nginx
http {
resolver 127.0.0.53; # требуется для директивы 'acme_client'
acme_client example https://acme-v02.api.letsencrypt.org/directory;
server {
listen 80; # Необязательно, если нет сервера,
# слушающего порт HTTP‑проверки
# (см. директиву 'acme_http_port')
listen 443 ssl;
server_name example.com www.example.com;
acme example;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
}
}
```
Как уже отмечалось,
порт 80 должен быть открыт для приема вызовов ACME по HTTP.
Если ни один сервер не слушает порт HTTP‑проверки,
модуль создаст отдельный слушающий сокет на порту 80
(или указанном в [acme_http_port](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-http-port)). Отдельный блок
[server](https://angie.software//angie/docs/configuration/modules/http/index.md#server) не требуется.
## DNS-проверка
Проверка работает автоматически.
Суть в том, что при получении запроса на сертификат
ACME-сервер выполняет [специальный DNS-запрос](https://datatracker.ietf.org/doc/html/rfc8555#section-8.4)
к поддомену `_acme-challenge.` проверяемого домена.
После получения ожидаемого ответа ACME-сервер подтверждает,
что домен принадлежит клиенту.
Наш модуль ACME отслеживает такие запросы и обрабатывает их автоматически,
при условии, что ваши записи DNS настроены должным образом,
чтобы указать сервер Angie в качестве авторитетного сервера имен
для поддомена `_acme-challenge.`.
#### NOTE
Сервер Angie должен быть доступен из интернета
на UDP-порту 53 (или указанном в [acme_dns_port](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-dns-port)).
Если сервер находится за межсетевым экраном,
убедитесь, что этот порт открыт для входящих соединений.
Например, чтобы подтвердить домен `example.com`,
используя сервер Angie с IP-адресом `93.184.215.14`,
DNS-конфигурация вашего домена должна включать следующие записи:
```none
_acme-challenge.example.com. 60 IN NS ns.example.com.
ns.example.com. 60 IN A 93.184.215.14
```
Эта конфигурация делегирует разрешение DNS для
`_acme-challenge.example.com` на `ns.example.com`,
обеспечивая доступность `ns.example.com`
путем сопоставления с IP-адресом (`93.184.215.14`).
#### WARNING
Распространение изменений NS-записей может занимать от нескольких минут
до 48 часов в зависимости от TTL и DNS-провайдера.
Рекомендуется проверить корректность настройки перед запросом сертификата.
Для проверки корректности настройки DNS можно использовать следующие команды:
```console
$ dig NS _acme-challenge.example.com +short # Проверка NS-записи для поддомена _acme-challenge
ns.example.com.
$ dig A ns.example.com +short # Проверка A-записи для сервера имен
93.184.215.14
$ nc -zv 93.184.215.14 53 # Проверка доступности DNS-сервера на порту 53
```
Этот способ позволяет запрашивать wildcard-сертификаты, например сертификат,
включающий запись `*.example.com` в разделе Subject Alternative Name
(SAN). Чтобы в явной форме запросить сертификат для поддомена, например
`www.example.com`, следует отдельно подтвердить этот поддомен описанным
выше способом.
#### WARNING
Применимость данного сценария во многом зависит от возможностей,
предоставляемых вашим DNS-провайдером;
некоторые провайдеры не позволяют выполнять такие настройки.
### Пример конфигурации
В целом, конфигурация схожа с примером из предыдущего раздела.
Нет необходимости в настройках, специфичных для HTTP;
вместо этого достаточно установить `challenge=dns`
для директивы [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client).
Здесь ACME-клиент с именем `example` управляет сертификатами для
`example.com` и `*.example.com`:
```nginx
http {
resolver 127.0.0.53;
acme_client example https://acme-v02.api.letsencrypt.org/directory
challenge=dns;
server {
server_name example.com *.example.com;
acme example;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
}
}
```
## ALPN-проверка
Проверка работает автоматически. ACME‑сервер устанавливает TLS‑соединение и
запрашивает через ALPN протокол `acme-tls/1`. Модуль отдает временный
сертификат для валидационного запроса.
Чтобы использовать этот способ, задайте `challenge=alpn` в директиве
[acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) и убедитесь, что ваш TLS‑слушатель доступен на порту 443
(или на используемом TLS‑порту).
### Пример конфигурации
Конфигурация аналогична предыдущим разделам; достаточно задать
`challenge=alpn` для директивы [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) и убедиться, что
TLS-сервер доступен на порту 443.
Здесь ACME-клиент с именем `example` управляет сертификатом для
`example.com` и `www.example.com`:
```nginx
http {
resolver 127.0.0.53;
acme_client example https://acme-v02.api.letsencrypt.org/directory
challenge=alpn;
server {
listen 443 ssl;
server_name example.com www.example.com;
acme example;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
}
}
```
## Проверка с помощью хуков
В отличие от предыдущих способов,
эта проверка требует дополнительных усилий.
Здесь ACME-сервер производит обычную [HTTP-проверку](#acme-config-http)
или [DNS-проверку](#acme-config-dns),
но обращается не к самому серверу Angie, а к внешнему сервису,
которым сервер Angie управляет с помощью вызовов-хуков ([acme_hook](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook)).
В свою очередь, этот сервис настраивает отдельный DNS- или HTTP-сервер,
куда и направляются запросы ACME-сервера.
Получив ожидаемый ответ от настроенного таким образом DNS- или HTTP-сервера,
ACME-сервер подтверждает, что домен принадлежит клиенту.
Когда для выпуска или обновления сертификата требуется проверка домена,
Angie формирует внутренний запрос
к именованному `location`, содержащему директиву [acme_hook](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook).
Способ обработки этого запроса полностью зависит
от других директив, заданных в том же `location`.
Общая схема такова:
1. Создайте именованный `location` с директивой [acme_hook](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook).
2. Настройте обработчик запроса в том же `location`
с помощью модуля, подходящего для вашей конфигурации:
[fastcgi_pass](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass) для FastCGI,
[proxy_pass](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) для HTTP,
`cgi` для CGI-скриптов и т. д.
3. Передайте обработчику [переменные](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme-variables) ACME
с помощью поддерживаемого им механизма,
например, `fastcgi_param` для FastCGI
или `cgi_set_var` для CGI.
Обработчик должен возвращать код состояния `2xx`,
который можно передать через заголовок `Status`.
Любой другой код считается ошибкой,
и обновление сертификата прекращается.
Вывод обработчика игнорируется.
### Минимальная конфигурация
Независимо от используемого обработчика,
`location` для хука имеет следующую структуру:
```nginx
location @acme_hook_location {
acme_hook example;
# Handler directive (fastcgi_pass, proxy_pass, cgi on, ...)
# Pass ACME variables using the handler's mechanism:
# ACME_HOOK — $acme_hook_name ("add" or "remove")
# ACME_CHALLENGE — $acme_hook_challenge ("dns" or "http")
# ACME_DOMAIN — $acme_hook_domain
# ACME_TOKEN — $acme_hook_token
# ACME_KEYAUTH — $acme_hook_keyauth
}
```
При DNS-проверке обработчик должен использовать `ACME_HOOK`
для определения действия:
если значение `add`,
создать TXT-запись для `_acme-challenge.*ACME_DOMAIN*`
со значением из `ACME_KEYAUTH`;
если значение `remove`, удалить эту запись.
### Пример с FastCGI
Здесь настраивается [ACME-клиент](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) `example`
для подтверждения домена при помощи DNS-вызова,
на что указывает параметр `challenge=dns` директивы [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client).
Блок `server` применяется ко всем поддоменам `example.com`
(например, `*.example.com`)
и использует ACME-клиент `example` для управления сертификатами,
что указано в директиве [acme](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#id4).
Именованный блок `location` обрабатывает вызовы хуков.
Директива [acme_hook](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook) связывает его
с ACME-клиентом `example`.
Запросы хуков отправляются на локальный FastCGI-сервер
на порту 9000 с помощью [fastcgi_pass](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass).
Директивы `fastcgi_param` передают
переменные ACME во внешний сервис.
```nginx
acme_client example https://acme-v02.api.letsencrypt.org/directory
challenge=dns;
server {
listen 80;
server_name *.example.com;
acme example;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
location @acme_hook_location {
acme_hook example;
fastcgi_pass localhost:9000;
fastcgi_param ACME_CLIENT $acme_hook_client;
fastcgi_param ACME_HOOK $acme_hook_name;
fastcgi_param ACME_CHALLENGE $acme_hook_challenge;
fastcgi_param ACME_DOMAIN $acme_hook_domain;
fastcgi_param ACME_TOKEN $acme_hook_token;
fastcgi_param ACME_KEYAUTH $acme_hook_keyauth;
include fastcgi.conf;
}
}
```
Пример соответствующего внешнего FastCGI-сервиса на Perl:
```perl
#!/usr/bin/perl
use strict; use warnings;
use FCGI;
my $socket = FCGI::OpenSocket(":9000", 5);
my $request = FCGI::Request(\*STDIN, \*STDOUT, \*STDERR, \%ENV, $socket);
while ($request->Accept() >= 0) {
print "\r\n";
my $client = $ENV{ACME_CLIENT};
my $hook = $ENV{ACME_HOOK};
my $challenge = $ENV{ACME_CHALLENGE};
my $domain = $ENV{ACME_DOMAIN};
my $token = $ENV{ACME_TOKEN};
my $keyauth = $ENV{ACME_KEYAUTH};
if ($hook eq 'add') {
DNS_set_TXT_record("_acme-challenge.$domain.", $keyauth);
} elsif ($hook eq 'remove') {
DNS_clear_TXT_record("_acme-challenge.$domain.");
}
};
FCGI::CloseSocket($socket);
```
Здесь `DNS_set_TXT_record()` и `DNS_clear_TXT_record()` —
функции, предположительно добавляющие и удаляющие TXT-записи
в конфигурации некого внешнего DNS-сервера, к которому и обратится ACME-сервер.
В этих записях должны содержаться переданные сервером Angie данные,
что позволит внешнему DNS-серверу успешно пройти проверку,
аналогичную описанной в разделе [DNS-проверка](#acme-config-dns).
Подробности реализации таких функций выходят за рамки этого руководства;
так, например, передавать параметры можно и через URI запроса:
```nginx
# ...
location @acme_hook_location {
acme_hook example uri=/acme_hook/$acme_hook_name?domain=$acme_hook_domain&key=$acme_hook_keyauth;
fastcgi_pass localhost:9000;
fastcgi_param REQUEST_URI $request_uri;
fastcgi_param ACME_CLIENT $acme_hook_client;
fastcgi_param ACME_CHALLENGE $acme_hook_challenge;
fastcgi_param ACME_TOKEN $acme_hook_token;
include fastcgi.conf;
}
```
### Пример с PHP-FPM
Еще один пример, с использованием PHP-FPM:
```nginx
location @acme_hook_location {
acme_hook example;
root /var/www/dns;
fastcgi_pass unix:/run/php-fpm/php-dns.sock;
fastcgi_index hook.php;
fastcgi_param SCRIPT_FILENAME /var/www/dns/hook.php;
include fastcgi_params;
fastcgi_param ACME_CLIENT $acme_hook_client;
fastcgi_param ACME_HOOK $acme_hook_name;
fastcgi_param ACME_CHALLENGE $acme_hook_challenge;
fastcgi_param ACME_DOMAIN $acme_hook_domain;
fastcgi_param ACME_TOKEN $acme_hook_token;
fastcgi_param ACME_KEYAUTH $acme_hook_keyauth;
}
```
```ini
[dns]
listen = /run/php-fpm/php-dns.sock
listen.mode = 0666
user = angie
group = angie
chdir = /var/www/dns
# ...
```
Переданные параметры доступны в PHP через `$_SERVER['...']`.
## ACME в потоковом модуле
Потоковый модуль [ACME](https://angie.software//angie/docs/configuration/modules/stream/stream_acme.md#stream-acme) позволяет автоматизировать
выпуск и использование сертификатов для TCP-трафика.
Для его корректной работы необходимо сначала настроить HTTP-аналог:
ACME-клиент должен быть объявлен в контексте `http`,
а сам блок `stream` должен располагаться *после* блока `http`
в конфигурации.
### Пример конфигурации
По умолчанию для получения сертификатов используется режим HTTP-проверки.
Для него, как упоминалось в разделе [HTTP-проверка](#acme-config-http),
нужен HTTP-сервер, слушающий на порту 80:
```nginx
# HTTP-часть
http {
resolver 127.0.0.53;
# ACME-клиент для потоковой части
acme_client example https://acme-v02.api.letsencrypt.org/directory;
# Сервер для HTTP-проверки
server {
listen 80;
return 444;
}
}
# Потоковая часть
stream {
server {
listen 12345 ssl;
proxy_pass backend_upstream;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
server_name example.com www.example.com;
acme example; # ссылка на ACME-клиент, определенный в HTTP-части
}
upstream backend_upstream {
server 127.0.0.1:54321;
}
}
```
Также можно использовать DNS-проверку,
настроив `challenge=dns` в директиве [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client);
тогда сервер будет не нужен.
## Миграция с **certbot**
Если до [перехода с nginx на Angie](https://angie.software//angie/docs/configuration/migration.md#migration)
вы использовали [certbot](https://certbot.eff.org/)
для получения и продления SSL-сертификатов от центра сертификации Let's Encrypt,
выполните следующие шаги, чтобы перейти к использованию нашего модуля ACME.
Предположим, вы настроили сертификаты следующим образом:
```console
$ sudo certbot --nginx -d example.com -d www.example.com
```
Автоматически созданная при этом конфигурация
обычно находится в файле `/etc/nginx/sites-available/example.conf`
и выглядит приблизительно так:
```nginx
server {
listen 80;
server_name example.com www.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
server_name example.com www.example.com;
root /var/www/example;
index index.html;
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
include /etc/letsencrypt/options-ssl-nginx.conf;
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}
```
В примере выше выделены строки, которые потребуется изменить.
В зависимости от ваших обстоятельств и предпочтений настройте
[HTTP-проверку](#acme-config-http)
или [DNS-проверку](#acme-config-dns) с помощью модуля ACME.
Итоговая [конфигурация Angie](https://angie.software//angie/docs/configuration/configfile.md#configfile)
может выглядеть приблизительно так:
```nginx
http {
resolver 127.0.0.53;
acme_client example https://acme-v02.api.letsencrypt.org/directory;
server {
listen 80;
server_name example.com www.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
server_name example.com www.example.com;
root /var/www/example;
index index.html;
acme example;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
}
}
```
Не забудьте перезагрузить конфигурацию
[после изменения](https://angie.software//angie/docs/configuration/runtime.md#control-config-change):
```console
$ sudo kill -HUP $(cat /run/angie.pid)
```
Убедившись, что эта конфигурация работает,
вы можете удалить сертификаты **certbot**,
а также отключить или целиком удалить его с сервера,
если он больше нигде не используется,
например:
```console
$ sudo rm -rf /etc/letsencrypt
$ sudo systemctl stop certbot.timer
$ sudo systemctl disable certbot.timer
$ # -- или --
$ sudo rm /etc/cron.d/certbot
$ sudo apt remove certbot
$ # -- или --
$ sudo dnf remove certbot
```
# https://angie.software/angie/docs/configuration/oidc.md
# Настройка аутентификации OIDC
В этом руководстве описано, как настроить аутентификацию OpenID Connect (OIDC),
используя Google в качестве провайдера идентификации
и веб-сервер Angie со скриптами на Lua.
Эта реализация защищает внутренние конечные точки с помощью аутентификации OAuth2/OIDC
и демонстрирует один из способов ограничить доступ по доменам электронной почты.
Это лишь один из возможных подходов; вы можете реализовать контроль доступа
любым удобным вам способом — например, поддерживать списки разрешённых пользователей,
проверять принадлежность к домену или группам в ответе провайдера
или использовать произвольные claims вашего внутреннего IAM.
## Архитектура
Предлагаемая конфигурация OIDC включает:
- Angie — с поддержкой Lua-модуля для обработки OIDC
- [lua-resty-openidc](https://github.com/zmartzone/lua-resty-openidc) — Lua-библиотека OpenResty для аутентификации через OIDC
- Google OAuth2 — провайдер идентификации
- Docker Compose — используется в примере только для быстрого запуска;
в продакшене используйте подходящий вариант развертывания
## Требования
Перед настройкой OIDC убедитесь, что у вас есть:
1. Веб-сервер Angie с поддержкой [Lua-модуля](https://angie.software//angie/docs/installation/external-modules/lua.md#external-lua)
2. Docker и Docker Compose (для развертывания)
3. Проект в Google Cloud Console
4. OAuth2-учётные данные от Google
## Настройка Google OAuth2
Чтобы настроить Google как OIDC-провайдера:
1. Перейдите в [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
2. Создайте новый проект или выберите существующий
3. Настройте экран согласия OAuth (External или Internal) и опубликуйте его
4. Создайте OAuth2-учётные данные:
- Тип приложения: Web application
- Разрешённые URI для редиректа: `http://localhost/auth/callback`
5. Сохраните свои `client_id` и `client_secret`
#### NOTE
Стандартные Google Identity Services уже поддерживают OIDC;
устаревший Google+ API не требуется.
Включайте дополнительные Google API только при необходимости.
## Настройка конфигурации
Начнём с необходимых конфигурационных файлов.
### Конфигурация Docker Compose
Развёртывание через Docker использует следующий конфиг:
```yaml
services:
angie:
image: docker.angie.software/angie:templated
environment:
ANGIE_LOAD_MODULES: "lua"
ports:
- 80:80
volumes:
- ./files/etc/angie/http.d:/etc/angie/http.d
```
Эта конфигурация:
- Использует [templated-образ Angie](https://angie.software//angie/docs/installation/docker.md#docker-templated) с поддержкой Lua
- Загружает [Lua-модуль](https://angie.software//angie/docs/installation/external-modules/lua.md#external-lua) для OIDC
- Пробрасывает порт 80
- Монтирует локальные конфигурационные файлы
Для запуска «из коробки» скачайте
[`OIDC quick-start bundle`](https://angie.software//angie/docs/configuration/oidc-sample-config.zip),
установите `client_id` и `client_secret` в
`files/etc/angie/http.d/oidc.lua`,
и всё сразу заработает.
### Скрипт аутентификации OIDC
Создайте скрипт OIDC,
который обрабатывает логику аутентификации с использованием библиотеки
`lua-resty-openidc`:
```lua
access_by_lua_block {
local res, err = require("resty.openidc").authenticate({
redirect_uri = "http://localhost/auth/callback",
discovery = "https://accounts.google.com/.well-known/openid-configuration",
logout_path = "/auth/logout",
redirect_after_logout_uri = "/auth/logged-out",
revoke_tokens_on_logout = true,
client_id = "YOUR_CLIENT_ID",
client_secret = "YOUR_CLIENT_SECRET"
})
}
```
Параметры конфигурации:
- `redirect_uri`: URL-адрес обратного вызова после успешной аутентификации
- `discovery`: discovery-endpoint Google OIDC
- `logout_path`: путь выхода пользователя
- `redirect_after_logout_uri`: куда перенаправлять после выхода
- `revoke_tokens_on_logout`: отзывать токены при logout
- `client_id` и `client_secret`: учётные данные OAuth2
### Конфигурация Angie
Настройте Angie с необходимыми блоками [location](https://angie.software//angie/docs/configuration/modules/http/index.md#location)
для аутентификации OIDC.
#### Защищённые ресурсы
Чтобы защитить ресурсы:
```nginx
location /internal/ {
include /etc/angie/http.d/oidc.lua;
proxy_pass http://127.0.0.1/status/;
}
```
Здесь:
- Путь `/internal/` защищён OIDC
- Запросы проксируются к [внутреннему API](https://angie.software//angie/docs/configuration/modules/http/http_api.md#http-api) на `/status/`
#### Конечные точки аутентификации
Настройка OAuth2-эндпоинтов:
```nginx
location /auth/callback {
include /etc/angie/http.d/oidc.lua;
}
location /auth/logout {
include /etc/angie/http.d/oidc.lua;
}
location /auth/logged-out {
default_type text/plain;
return 200 "You have been logged out. Bye!";
}
```
Назначение маршрутов:
- `/auth/callback`: обработка callback от Google
- `/auth/logout`: инициирует выход
- `/auth/logged-out`: страница после выхода
#### Доступ к внутреннему API
Настройте ограниченный доступ к API:
```nginx
location /status/ {
api /status/;
allow 127.0.0.1;
deny all;
}
```
Это обеспечивает:
- Доступ к [status API Angie](https://angie.software//angie/docs/configuration/modules/http/http_api.md#http-api)
- Доступ только с localhost
- OIDC-защиту при доступе через `/internal/`
## Этапы развертывания
### Обновление конфигурации
1. Обновите учетные данные OAuth2 в файле Lua:
Замените значения в `oidc.lua`:
- `client_id` на ваш Google OAuth2 Client ID
- `client_secret` на ваш Client Secret
### Запуск сервисов
1. Запустите Docker-сервисы:
```console
$ docker-compose up -d
```
2. Проверьте работу:
- Откройте `http://localhost/internal/`
- Должна появиться переадресация на Google
- После логина вы попадёте в защищённый раздел
## Настройки безопасности
### Ограничение по домену e-mail
Реализуйте проверку домена:
```lua
if not string.match(res.user.email, "gmail.com$") then
ngx.exit(ngx.HTTP_FORBIDDEN)
end
```
В продакшене:
- замените `gmail.com` на домен вашей компании
- используйте whitelist пользователей
- добавьте контроль ролей
### Управление токенами
В реализации OIDC предусмотрено:
- автоматический отзыв токенов при logout (`revoke_tokens_on_logout = true`)
- безопасное управление сессией в lua-resty-openidc
- следование лучшим практикам OAuth2/OIDC
#### WARNING
Для продакшена:
- Всегда используйте HTTPS для callback-адресов
- Храните client secrets безопасно, не в репозитории
- Настройте корректные таймауты и обновление сессий
- Мониторьте логи аутентификации
## Поток аутентификации
Стандартный поток OIDC выглядит так:
1. Пользователь запрашивает защищённый URL (например `http://localhost/internal/`)
2. При отсутствии сессии — перенаправление на Google OAuth2
3. Пользователь входит в аккаунт Google
4. Google возвращает код авторизации на `/auth/callback`
5. Сервер запрашивает access token и ID token
6. Проверяет данные пользователя (включая домен e-mail)
7. Предоставляет доступ к ресурсу
Процесс logout:
1. Пользователь переходит по `http://localhost/auth/logout`
2. Токены отзываются у Google
3. Локальная сессия очищается
4. Переход на `/auth/logged-out`
## Расширенная конфигурация
Ограничить доступ одним доменом:
```lua
if not string.match(res.user.email, "yourcompany.com$") then
ngx.exit(ngx.HTTP_FORBIDDEN)
end
```
Несколько разрешённых доменов:
```lua
local allowed_domains = {"company1.com", "company2.com", "gmail.com"}
local email_valid = false
for _, domain in ipairs(allowed_domains) do
if string.match(res.user.email, domain .. "$") then
email_valid = true
break
end
end
if not email_valid then
ngx.exit(ngx.HTTP_FORBIDDEN)
end
```
### Доступ к данным пользователя
Получить дополнительные claims:
```lua
-- Доступ к данным из ID token
local user_name = res.user.name
local user_picture = res.user.picture
local user_locale = res.user.locale
local user_email = res.user.email
```
Эти данные можно использовать для логирования,
персонализации или дополнительных решений по контролю доступа.
# https://angie.software/angie/docs/configuration/ssl.md
# Настройка SSL
Чтобы настроить HTTPS-сервер, необходимо включить параметр [ssl](https://angie.software//angie/docs/configuration/modules/http/index.md#listen)
на слушающих сокетах в блоке [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server), а также указать местоположение
файлов с сертификатом сервера и секретным ключом:
```nginx
server {
listen 443 ssl;
server_name www.example.com;
ssl_certificate www.example.com.crt;
ssl_certificate_key www.example.com.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
#...
}
```
Сертификат сервера является публичным. Он посылается каждому клиенту,
соединяющемуся с сервером. Секретный ключ следует хранить в файле с ограниченным
доступом (права доступа должны позволять главному процессу Angie читать этот
файл). Секретный ключ можно также хранить в одном файле с сертификатом.
```nginx
ssl_certificate www.example.com.cert;
ssl_certificate_key www.example.com.cert;
```
При этом права доступа к файлу следует также ограничить. Несмотря на то, что и
сертификат, и ключ хранятся в одном файле, клиенту посылается только сертификат.
С помощью директив [ssl_protocols](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-protocols) и [ssl_ciphers](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ciphers) можно ограничить
соединения использованием только "сильных" версий и шифров SSL/TLS. По умолчанию
Angie использует:
```nginx
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
```
Поэтому их явная настройка в общем случае не требуется.
## Оптимизация HTTPS-сервера
SSL-операции потребляют дополнительные ресурсы процессора. На мультипроцессорных
системах следует запускать несколько [рабочих процессов](https://angie.software//angie/docs/configuration/modules/core.md#worker-processes), не меньше числа доступных процессорных ядер. Наиболее
ресурсоемкой для процессора является операция SSL-рукопожатия, в рамках которого
формируются криптографические параметры сессии. Существует два способа
уменьшения числа этих операций, производимых для каждого клиента: использование
постоянных ([keepalive](https://angie.software//angie/docs/configuration/modules/http/index.md#keepalive-timeout)) соединений, позволяющих в
рамках одного соединения обрабатывать сразу несколько запросов, и повторное
использование параметров SSL-сессии для предотвращения необходимости выполнения
SSL-рукопожатия для параллельных и последующих соединений. Сессии хранятся в
кэше SSL-сессий, разделяемом между рабочими процессами и настраиваемом
директивой [ssl_session_cache](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-session-cache). В 1 мегабайт кэша помещается около 4000
сессий. Таймаут кэша по умолчанию равен 5 минутам. Он может быть увеличен с
помощью директивы [ssl_session_timeout](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-session-timeout). Вот пример конфигурации,
оптимизированной под многоядерную систему с 10-мегабайтным разделяемым кэшем
сессий:
```nginx
worker_processes auto;
http {
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
server {
listen 443 ssl;
server_name www.example.com;
keepalive_timeout 70;
ssl_certificate www.example.com.crt;
ssl_certificate_key www.example.com.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
#...
```
## Цепочки SSL-сертификатов
Некоторые браузеры могут выдавать предупреждение о сертификате, подписанном
общеизвестным центром сертификации, в то время как другие браузеры без проблем
принимают этот же сертификат. Так происходит потому, что центр, выдавший
сертификат, подписал его промежуточным сертификатом, которого нет в базе данных
сертификатов общеизвестных доверенных центров сертификации, распространяемой
вместе с браузером. В подобном случае центр сертификации предоставляет "связку"
сертификатов, которую следует присоединить к сертификату сервера. Сертификат
сервера следует разместить перед связкой сертификатов в скомбинированном файле:
```console
$ cat www.example.com.crt bundle.crt > www.example.com.chained.crt
```
Полученный файл следует указать в директиве [ssl_certificate](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate):
```nginx
server {
listen 443 ssl;
server_name www.example.com;
ssl_certificate www.example.com.chained.crt;
ssl_certificate_key www.example.com.key;
#...
}
```
Если сертификат сервера и связка сертификатов были соединены в неправильном
порядке, Angie не запустится и выдаст сообщение об ошибке:
> SSL_CTX_use_PrivateKey_file(" ... /www.example.com.key") failed
> : (SSL: error:0B080074:x509 certificate routines:
> X509_check_private_key:key values mismatch)
Поскольку Angie попытается использовать секретный ключ с первым сертификатом
из связки вместо сертификата сервера.
Браузеры обычно сохраняют полученные промежуточные сертификаты, подписанные
доверенными центрами сертификации, поэтому активно используемые браузеры уже
могут иметь требуемые промежуточные сертификаты и не выдать предупреждение о
сертификате, присланном без связанной с ним цепочки сертификатов. Убедиться в
том, что сервер присылает полную цепочку сертификатов, можно при помощи утилиты
командной строки **openssl**, например:
```console
$ openssl s_client -connect www.godaddy.com:443
Certificate chain
0 s:/C=US/ST=Arizona/L=Scottsdale/1.3.6.1.4.1.311.60.2.1.3=US
/1.3.6.1.4.1.311.60.2.1.2=AZ/O=GoDaddy.com, Inc
/OU=MIS Department/CN=www.GoDaddy.com
/serialNumber=0796928-7/2.5.4.15=V1.0, Clause 5.(b)
i:/C=US/ST=Arizona/L=Scottsdale/O=GoDaddy.com, Inc.
/OU=http://certificates.godaddy.com/repository
/CN=Go Daddy Secure Certification Authority
/serialNumber=07969287
1 s:/C=US/ST=Arizona/L=Scottsdale/O=GoDaddy.com, Inc.
/OU=http://certificates.godaddy.com/repository
/CN=Go Daddy Secure Certification Authority
/serialNumber=07969287
i:/C=US/O=The Go Daddy Group, Inc.
/OU=Go Daddy Class 2 Certification Authority
2 s:/C=US/O=The Go Daddy Group, Inc.
/OU=Go Daddy Class 2 Certification Authority
i:/L=ValiCert Validation Network/O=ValiCert, Inc.
/OU=ValiCert Class 2 Policy Validation Authority
/CN=http://www.valicert.com//emailAddress=info@valicert.com
```
В этом примере субъект ("s") сертификата №0 сервера www.GoDaddy.com подписан
издателем ("i"), который в свою очередь является субъектом сертификата №1,
подписанного издателем, который в свою очередь является субъектом сертификата
№2, подписанного общеизвестным издателем ValiCert, Inc., чей сертификат хранится
во встроенной в браузеры базе данных сертификатов.
Если связку сертификатов не добавили, будет показан только сертификат сервера
под номером 0.
## Единый HTTP/HTTPS сервер
Можно настроить единый сервер, который обслуживает как HTTP-, так и
HTTPS-запросы:
```nginx
server {
listen 80;
listen 443 ssl;
server_name www.example.com;
ssl_certificate www.example.com.crt;
ssl_certificate_key www.example.com.key;
#...
}
```
## Выбор HTTPS-сервера по имени
Типичная проблема возникает при настройке двух и более HTTPS-серверов, слушающих
на одном и том же IP-адресе:
```nginx
server {
listen 443 ssl;
server_name www.example.com;
ssl_certificate www.example.com.crt;
#...
}
server {
listen 443 ssl;
server_name www.example.org;
ssl_certificate www.example.org.crt;
#...
}
```
В такой конфигурации браузер получит сертификат сервера по умолчанию, т.е.
www.example.com, независимо от запрашиваемого имени сервера. Это связано с
поведением протокола SSL. SSL-соединение устанавливается до того, как браузер
посылает HTTP-запрос, и Angie не знает имени запрашиваемого сервера.
Следовательно, он лишь может предложить сертификат сервера по умолчанию.
Наиболее старым и надежным способом решения этой проблемы является назначение
каждому HTTPS-серверу своего IP-адреса:
```nginx
server {
listen 192.168.1.1:443 ssl;
server_name www.example.com;
ssl_certificate www.example.com.crt;
#...
}
server {
listen 192.168.1.2:443 ssl;
server_name www.example.org;
ssl_certificate www.example.org.crt;
#...
}
```
## SSL-сертификат с несколькими именами
Существуют и другие способы, позволяющие использовать один и тот же IP-адрес
сразу для нескольких HTTPS-серверов. Все они, однако, имеют свои недостатки.
Одним из таких способов является использование сертификата с несколькими именами
в поле SubjectAltName сертификата, например www.example.com и
www.example.org. Однако, длина поля SubjectAltName ограничена.
Другим способом является использование wildcard-сертификата, например
\*.example.org. Такой сертификат защищает все поддомены указанного домена, но
только на заданном уровне. Под такой сертификат подходит www.example.org, но
не подходят example.org и www.sub.example.org. Эти два метода также могут
быть объединены. Сертификат может содержать как точные, так и wildcard-имена в
поле SubjectAltName, например example.org и \*.example.org.
Лучше всего разместить файл сертификата с несколькими именами и его секретный
ключ на уровне конфигурации http, чтобы все серверы унаследовали их
единственную копию в памяти.
```nginx
ssl_certificate common.crt;
ssl_certificate_key common.key;
server {
listen 443 ssl;
server_name www.example.com;
#...
}
server {
listen 443 ssl;
server_name www.example.org;
#...
}
```
## Указание имени сервера
Более общее решение для работы нескольких HTTPS-серверов на одном IP-адресе —
расширение Server Name Indication протокола TLS (SNI, [RFC 6066](https://datatracker.ietf.org/doc/html/rfc6066.html)), которое позволяет
браузеру передать запрашиваемое имя сервера во время SSL-рукопожатия, а значит,
сервер будет знать, какой сертификат ему следует использовать для соединения.
Сейчас SNI поддерживается большинством современных браузеров, однако может не
использоваться некоторыми старыми или специализированными клиентами.
Если Angie был собран с поддержкой SNI, то при запуске Angie с ключом
`-V` об этом сообщается:
```console
$ angie -V
...
TLS SNI support enabled
...
```
Однако если Angie, собранный с поддержкой SNI, в процессе работы подгружает
библиотеку OpenSSL, в которой нет поддержки SNI, Angie выдает
предупреждение:
> Angie was built with SNI support, however, now it is linked
> dynamically to an OpenSSL library which has no tlsext support,
> therefore SNI is not available
# https://angie.software/angie/docs/configuration/cluster.md
# Настройка кластера Angie
Это руководство описывает процесс создания отказоустойчивого кластера Angie
с автоматической синхронизацией конфигурации
и переключением виртуального IP-адреса.
## Подготовка узлов кластера для синхронизации
Первым шагом необходимо подготовить все узлы кластера,
настроив учетные записи пользователей
и обеспечив безопасный доступ между серверами.
### Настройка пользователей и прав доступа
Создайте на всех узлах пользователя
(например, `angie-ha-sync`) с правами `sudo`:
```console
$ sudo adduser angie-ha-sync
```
Задайте пароль при необходимости:
```console
$ sudo passwd angie-ha-sync
```
#### NOTE
В некоторых ОС (например, в Альт Линукс)
следует добавить пользователя в группу `wheel`:
```console
$ sudo usermod -a -G wheel angie-ha-sync
```
Для работы с `rsync` при включенном МКЦ в Astra Linux задайте
корректный уровень целостности:
```console
$ sudo pdpl-user -i 63 angie-ha-sync
```
Настройте sudo без пароля:
```console
$ echo "angie-ha-sync ALL=(ALL:ALL) NOPASSWD:ALL" | sudo tee -a /etc/sudoers
```
На мастер-узле создайте SSH-ключи и скопируйте их на резервные узлы:
```console
$ su - angie-ha-sync
$ ssh-keygen -t rsa
$ ssh-copy-id angie-ha-sync@node2_hostname
```
#### WARNING
Перед копированием SSH-ключей убедитесь, что в файле
`/etc/ssh/sshd_config` установлена опция:
`PasswordAuthentication yes`
После настройки доступа по ключу установите значение `no` для повышения
безопасности.
#### NOTE
Для перекрестной синхронизации конфигурации Angie скопируйте ключи
пользователя на все узлы:
```console
$ scp -p ~angie-ha-sync/.ssh/id_rsa angie-ha-sync@node2_hostname:.ssh/
```
## Установка Angie и angie-ha-sync
После подготовки узлов необходимо установить основные компоненты кластера:
Angie и пакет для синхронизации конфигурации.
Настройте репозиторий на всех узлах по инструкции для пакетов вашей системы:
- [Инструкции для Angie](https://angie.software//angie/docs/installation/oss_packages.md#oss-packages)
- [Инструкции для Angie PRO](https://angie.software//angie/docs/installation/pro_packages.md#pro-packages)
### Установка angie-ha-sync
Модуль синхронизации конфигурации доступен в следующих пакетах:
- Angie: `angie-ha-sync`
- Angie PRO: `angie-pro-ha-sync`
#### NOTE
При установке этого пакета на чистую систему
по зависимостям будет установлен также соответствующий пакет
`angie` или `angie-pro`.
На всех узлах установите пакет с помощью пакетного менеджера вашей ОС, например:
```console
$ sudo {apk|apt|pkg|yum|zypper} {add|install} angie-pro-ha-sync
```
## Настройка синхронизации конфигурации
Следующий этап — настройка автоматической синхронизации конфигурационных файлов
между узлами кластера.
#### NOTE
Принцип работы синхронизации:
- Синхронизация выполняется через `rsync`.
- Происходит только при работающей службе Angie.
- Выполняется вручную (команда `angiehasync -Sd`).
- Работает в одном направлении: от мастер-узла к резервному.
- `rsync` запущен в режиме демона (daemon-mode).
### Настройка `rsync`
Создайте конфигурацию `rsync` (`/etc/rsyncd.conf`) на узлах:
```ini
[angie] # Директория с конфигурацией Angie
path = /etc/angie
# Пользователь для синхронизации
uid = angie-ha-sync
# Группа пользователя
gid = angie-ha-sync
# IP или подсеть, с которой разрешено подключение
hosts allow = 10.21.8.0/24
# Запретить все остальные
hosts deny = *
```
В зависимости от ОС запустите демон:
```console
$ sudo service rsyncd start # или $ sudo service rsync start
```
#### NOTE
Для некоторых систем есть готовые инструкции:
- [Альт](https://www.altlinux.org/Настройка_rsync-сервера)
- [Astra](https://wiki.astralinux.ru/pages/viewpage.action?pageId=41191598#id-Архивированиеивосстановлениефайловссохранениеммандатныхатрибутов-RSYNC)
### Настройка файла синхронизации
Отредактируйте `/etc/angiehasync/angiehasync.conf`:
```ini
M_NODE="" # Имя хоста или IP данной ноды
TARGET_HOSTS="" # Список хостов/IP для синхронизации (через пробел).
# На резервных узлах можно не указывать.
SSH_USER="user" # Пользователь для синхронизации (с правами администратора)
SSH_ID="/home/$SSH_USER/.ssh/id_rsa" # Путь к приватному ключу
```
#### NOTE
Для перекрестной синхронизации
заполните список `TARGET_HOSTS` на всех узлах;
при этом не следует включать в список текущий узел,
на котором в данный момент идет настройка.
### Настройка проверок работоспособности для Angie
Добавьте блок проверки работоспособности в конфигурацию Angie
(`/etc/angie/angie.conf`):
```ini
server {
listen unix:/tmp/angie_hcheck.sock; # Unix-сокет для проверки
access_log off;
error_log /dev/null;
default_type text/plain;
return 200 'ok\n';
}
```
Запустите Angie:
```console
$ sudo angie -t && sudo service angie start
```
Запустите синхронизацию:
```console
$ sudo angiehasync -Sd
```
#### NOTE
Скрипт автоматически проверит конфигурацию, выполнит синхронизацию со всеми
узлами и применит ее.
## Настройка Keepalived
Для автоматического переключения между узлами кластера используется Keepalived —
служба управления виртуальными IP-адресами (VIP).
#### NOTE
Если пакет `keepalived` не установлен — установите его:
```console
$ sudo {apk|apt|pkg|yum|zypper} {add|install} keepalived
```
Для связывания процессов с нелокальными IP-адресами
разрешите системе соответствующие действия:
```console
$ sudo sysctl -w net.ipv4.ip_nonlocal_bind=1
```
Подробнее:
[https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt#ip_nonlocal_bind](https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt#ip_nonlocal_bind)
Допустим, VIP `10.21.11.230`
назначается либо на мастер-узел (`10.21.8.26`),
либо на резервный (`10.21.8.27`).
Если Angie слушает этот VIP (`listen 10.21.11.230:80;`),
но адрес пока не назначен,
Angie не сможет стартовать без параметра `ip_nonlocal_bind`.
### Конфигурация Keepalived
На мастер-узле (`/etc/keepalived/keepalived.conf`):
```ini
global_defs {
enable_script_security
}
vrrp_script angie_check {
script "/usr/bin/curl -s --connect-timeout 5 -A 'angie_hcheck_script'
--no-buffer -XGET --unix-socket /tmp/angie_hcheck.sock http://hcheck/"
interval 5 user angie
}
vrrp_instance angie {
state MASTER interface enp0s2 virtual_router_id 254 priority 100
advert_int 2 unicast_src_ip 10.21.8.26
unicast_peer {
10.21.8.27
}
virtual_ipaddress {
10.21.11.230
} track_script {
angie_check
}
}
```
На резервном узле:
```ini
global_defs {
enable_script_security
}
vrrp_script angie_check {
script "/usr/bin/curl -s --connect-timeout 5 -A 'angie_hcheck_script'
--no-buffer -XGET --unix-socket /tmp/angie_hcheck.sock http://hcheck/"
interval 5 user angie
}
vrrp_instance angie {
state MASTER interface enp0s2 virtual_router_id 254 priority 99
advert_int 2 unicast_src_ip 10.21.8.27
unicast_peer {
10.21.8.26
}
virtual_ipaddress {
10.21.11.230
} track_script {
angie_check
}
}
```
#### NOTE
В разделе `vrrp_instance angie` задайте следующие значения:
- `unicast_src_ip` — IP текущего узла
- `unicast_peer` — IP соседних узлов
- `virtual_ipaddress` — виртуальный IP (VIP)
- `interface` — сетевой интерфейс
Запустите службу:
```console
$ sudo keepalived -t && sudo service keepalived start
```
### Разбор конфигурации Keepalived
Рассмотрим подробнее основные элементы конфигурации Keepalived
для понимания принципов работы кластера.
Конфигурация включает две части:
- `global_defs` — глобальные настройки
- `vrrp_instance` — параметры VRRP (переключение VIP)
Основные элементы:
- `enable_script_security` — разрешает выполнение скриптов проверки работоспособности
- `vrrp_script` — скрипт проверки Angie
- `state MASTER` — начальное состояние узла
- `priority` — приоритет (роль MASTER назначается наибольшему)
- `advert_int` — интервал VRRP-обновлений
- `unicast_src_ip` — IP текущего узла
- `unicast_peer` — IP соседей
- `virtual_ipaddress` — VIP-адрес
- `track_script` — контроль доступности через скрипты проверки работоспособности
#### NOTE
Если исходный мастер-узел восстановится,
он снова получит роль MASTER (приоритет выше).
Чтобы отключить возврат, используйте параметр `nopreempt`:
```none
vrrp_instance angie {
... nopreempt
}
```
## Проверка работы кластера
После завершения настройки необходимо протестировать работу кластера
и убедиться в корректном переключении между узлами.
Проверьте статус VIP:
```console
$ ip addr show enp0s2 | grep "10.21.11.230"
```
Протестируйте отказоустойчивость:
Остановите Angie на мастер-узле:
```console
$ sudo service angie stop
```
Проверьте переход VIP на резервный узел:
```console
$ ip addr show enp0s2 | grep "10.21.11.230"
```
Запустите Angie на мастер-узле снова:
```console
$ sudo service angie start
```
После этого VIP должен вернуться на мастер-узел.
# https://angie.software/angie/docs/configuration/nginx-unsupported-directives.md
# Неподдерживаемые директивы nginx
Большинство директив nginx работают в Angie без изменений, поэтому
существующая конфигурация обычно не требует правок. На этой странице
перечислены исключения — директивы, которые Angie удаляет, переименовывает
или объявляет устаревшими, — чтобы вы могли адаптировать конфигурацию при
переходе с nginx.
Низкоуровневые директивы тонкой настройки, которые не документирует и сам
nginx (например, настройка методов обработки соединений и сжатия gzip),
продолжают работать в Angie со значениями по умолчанию из nginx и намеренно
здесь не приводятся.
#### NOTE
Описание полного процесса миграции см. в
[руководстве по миграции](https://angie.software//angie/docs/configuration/migration.md#migration).
## Удалённые или опущенные
Эти директивы nginx не имеют эквивалента в Angie.
| Директива nginx | Примечания |
|---------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| `add_header_inherit`, `add_trailer_inherit` | Опущены из-за неудачного устройства; см. [История версий Angie](https://angie.software//angie/docs/oss_changes.md#oss-changes). |
## Переименованные
| Директива nginx | Директива Angie |
|-------------------------|---------------------------------------------------------------------------------------------------------------|
| `keepalive_min_timeout` | [lingering_timeout](https://angie.software//angie/docs/configuration/modules/http/index.md#lingering-timeout) |
## Устаревшие
Эти директивы по-прежнему работают, но выводят предупреждение; используйте
вместо них современную директиву.
| Директива nginx | Использовать вместо |
|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| `http2_idle_timeout` | [keepalive_timeout](https://angie.software//angie/docs/configuration/modules/http/index.md#keepalive-timeout) |
| `http2_max_requests` | [keepalive_requests](https://angie.software//angie/docs/configuration/modules/http/index.md#keepalive-requests) |
| `http2_recv_timeout` | [client_header_timeout](https://angie.software//angie/docs/configuration/modules/http/index.md#client-header-timeout) |
| `http2_max_field_size` | [large_client_header_buffers](https://angie.software//angie/docs/configuration/modules/http/index.md#large-client-header-buffers) |
| `http2_max_header_size` | [large_client_header_buffers](https://angie.software//angie/docs/configuration/modules/http/index.md#large-client-header-buffers) |
| `proxy_downstream_buffer` (stream) | [proxy_buffer_size](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-buffer-size) |
| `proxy_upstream_buffer` (stream) | [proxy_buffer_size](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-buffer-size) |
# https://angie.software/angie/docs/configuration/monitoring.md
# Веб-панель мониторинга Console Light
Angie предоставляет широкий спектр возможностей мониторинга своей работы;
помимо [метрик](https://angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) в API и модуля [Prometheus](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus), можно использовать визуальную
консоль, устанавливаемую в дополнение к серверу.
## Console Light
Console Light — это облегченный интерфейс мониторинга активности в
реальном времени, который отображает ключевые показатели нагрузки и
производительности сервера. Консоль основана на возможностях
[API-интерфейса](https://angie.software//angie/docs/configuration/modules/http/http_api.md#http-api) Angie; данные мониторинга активности
генерируются в реальном времени. Кроме того, консоль позволяет динамически
[изменять](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-config) конфигурацию Angie там, где эту возможность
предоставляет сам API.
Пример развернутой и настроенной консоли: [https://console.angie.software/](https://console.angie.software/)
## История версий
| Версия | Дата выпуска | Изменения |
|----------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1.8.2 | 23.01.2026 | Исправлена ссылка на документацию Angie ADC. |
| 1.8.1 | 08.09.2025 | Корректировка терминологии в разделе "Настройки" и в подсказках. |
| 1.8.0 | 03.07.2025 | Отображение метрик времени отклика
для проксируемых HTTP- и TCP/UDP-серверов |
| 1.7.2 | 07.04.2025 | Добавлена опция "busy" в контроллере фильтров на страницах
"HTTP/TCP/UDP-апстримы". |
| 1.7.1 | 04.04.2025 | Исправлены некорректные значения в таблицах "HTTP/Location Zones" на
странице "HTTP Zones". |
| 1.7.0 | 02.04.2025 | - Отображение точного объема данных в байтах при наведении курсора
- Новый статус `busy` для вышестоящих узлов в API статистики,
указывающий, что узел достиг лимита, заданного параметром `max_conns`
- Исправлены ссылки в документации |
| 1.6.1 | 27.01.2025 | - Исправлены опечатки
- Исправлена проблема, мешающая сборке проекта при разработке |
| 1.6.0 | 23.01.2025 | - Поддержка интернационализации с доступными локалями: `en`, `ru`.
- Добавлена функция закрепленного заголовка в компоненте таблицы.
- Поддержка единиц измерения данных в пебибайтах (PiB).
- Исправлен некорректный счетчик значений в виджете [HTTP-апстримы](#console-http-upstreams-widget) на главной странице.
- Теперь значения по умолчанию корректно используются на странице [HTTP-апстримы](#console-http-upstreams-page) в контексте ответа. |
| 1.5.0 | | Не выпускалась публично. |
| 1.4.0 | 08.08.2024 | Добавлено отображение статуса мониторинга в фавиконке веб-сайта. |
| 1.3.0 | 28.04.2024 | Добавлена возможность перевода сервера в состояние `draining`
в контексте группы проксируемых серверов. |
| 1.2.1 | 26.12.2023 | Добавлены активные проверки состояния в контексте `Stream`. |
| 1.2.0 | 25.12.2023 | Добавлено редактирование серверов в контексте `Stream`. |
## Установка и настройка
Console Light публикуется в виде пакетов
`angie-console-light` (Angie)
и
`angie-pro-console-light` (Angie PRO)
в
[наших репозиториях](https://angie.software//angie/docs/installation/index.md#install-packages)
и устанавливается так же, как и любой другой пакет;
кроме того, можно скачать исходный код
[с нашего веб-сайта](https://download.angie.software/files/angie-console-light/)
или
[GitHub](https://github.com/webserver-llc/angie-console-light).
После установки настройте консоль,
добавив такой фрагмент [location](https://angie.software//angie/docs/configuration/modules/http/index.md#location)
внутри блока [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server) в
[конфигурации сервера](https://angie.software//angie/docs/configuration/configfile.md#configfile)
(обратите внимание на комментарии):
```nginx
location /console/ {
# Только локальный доступ
allow 127.0.0.1;
deny all;
auto_redirect on;
alias /usr/share/angie-console-light/html/;
# Только во FreeBSD:
# alias /usr/local/www/angie-console-light/html/;
index index.html;
location /console/api/ {
api /status/;
}
# Чтобы после аутентификации работали функции редактирования (только PRO)
location /console/api/config/ {
auth_basic "Защищенный сайт";
auth_basic_user_file conf/htpasswd;
api /config/;
}
}
```
Не забудьте применить измененную конфигурацию:
```console
$ sudo angie -t && sudo service angie reload
```
После этого консоль будет доступна
на сервере, заданном блоком `server`,
по указанному для `location` пути;
выше путь задан как `/console/`.
Включить аутентификацию аналогично примеру выше
можно для произвольного раздела API, например:
```nginx
location /console/server_zones/ {
auth_basic "Защищенный сайт";
auth_basic_user_file conf/htpasswd;
}
```
Можно также запретить доступ к произвольному разделу
настроенного таким образом `location` для консоли, например:
```nginx
location /console/api/resolvers/ {
deny all;
}
```
## Интерфейс
Консоль представляет собой единый экран с набором вкладок,
каждая из которых содержит ряд виджетов с данными мониторинга.
### Вкладка Angie
Это основная вкладка, где в сводном виде отображаются основные показатели
мониторинга Angie, сведенные на основе данных из нескольких разделов API.
#### NOTE
Виджеты со статистикой отображаются, если настроены соответствующие блоки в
[конфигурации Angie](https://angie.software//angie/docs/configuration/configfile.md#configfile).
#### Виджет Сведения
Здесь выводится номер версии Angie со ссылкой на соответствующую
документацию, а также адрес сервера и время последней [перезагрузки
конфигурации](https://angie.software//angie/docs/configuration/runtime.md#control-config-change).
Кроме того, если включена директива [api_config_files](https://angie.software//angie/docs/configuration/modules/http/http_api.md#a-api-config-files),
ссылка *Configs* открывает список файлов конфигурации,
загруженных на сервере.
Затем каждый файл можно просмотреть в компактном виде с подсветкой синтаксиса.
#### Виджет Соединения
Здесь представлена основная статистика серверных соединений, формируемая на
основе раздела API `/status/connections/`:
| `Текущие` | Текущее количество соединений |
|-----------------|-----------------------------------------|
| `Принято/сек.` | Число принимаемых за секунду соединений |
| `Активные` | Число активных соединений |
| `Простаивающие` | Число соединений в состоянии ожидания |
| `Сброшенные` | Количество сброшенных соединений |
Также доступно:
| `Принято` | Общее число соединений, принятых с последней перезагрузки сервера |
|-------------|---------------------------------------------------------------------|
#### Виджет HTTP-зоны
#### WARNING
Требует задать директиву [status_zone](https://angie.software//angie/docs/configuration/modules/http/index.md#status-zone)
в контексте `server` или `location`.
Здесь представлена статистика зон разделяемой памяти контекста `http`,
формируемая на основе раздела API [/status/http/server_zones/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-server-zones):
| `Всего` | Общее количество зон |
|-----------|--------------------------------------------|
| `Проблем` | Количество зон с какими-либо проблемами |
| `Трафик` | Общий объем входящего и исходящего трафика |
#### Виджет HTTP-апстримы
#### WARNING
Требует задать директиву [zone](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone)
в блоке [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) в контексте `http`.
Здесь представлена статистика апстримов контекста `http`, формируемая на
основе раздела API [/status/http/upstreams/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-upstreams):
| `Всего` | Общее количество апстримов |
|-----------|------------------------------------------------|
| `Проблем` | Количество апстримов с какими-либо проблемами |
| `Серверы` | Статистика серверов с разделением по состоянию |
#### Виджет TCP/UDP-зоны
#### WARNING
Требует задать следующие директивы:
- `status_zone`
в контексте [server](https://angie.software//angie/docs/configuration/modules/http/index.md#status-zone) или [stream](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone);
- `limit_conn`
в контексте [server](https://angie.software//angie/docs/configuration/modules/http/http_api.md#limit-conn) или [stream](https://angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#s-limit-conn);
- [limit_conn_zone](https://angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#limit-conn-zone) в контексте `stream`.
Пример:
```nginx
stream {
# ...
limit_conn_zone $connection zone=limit-conn-stream:10m;
server {
# ...
limit_conn limit-conn-stream 1;
status_zone foo;
}
}
```
Здесь представлена статистика зон разделяемой памяти контекста `stream`,
формируемая на основе раздела API [/status/stream/server_zones/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-server-zones):
| `Соед. всего` | Общее количество клиентских соединений |
|-----------------|------------------------------------------------|
| `Соед. текущих` | Текущее количество клиентских соединений |
| `Соед./сек.` | Количество обрабатываемых в секунду соединений |
#### Виджет TCP/UDP-апстримы
#### WARNING
Требует задать директиву [zone](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone)
в блоке [upstream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) в контексте `stream`.
Здесь представлена статистика апстримов контекста `stream`, формируемая на
основе раздела API [/status/stream/upstreams/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-upstreams):
| `Всего` | Общее количество апстримов |
|-----------|------------------------------------------------|
| `Проблем` | Количество апстримов с какими-либо проблемами |
| `Серверы` | Статистика серверов с разделением по состоянию |
### Вкладка HTTP-зоны
#### WARNING
Требует задать директиву [status_zone](https://angie.software//angie/docs/configuration/modules/http/index.md#status-zone)
в контексте `server` или `location`.
#### Раздел Серверные зоны
Здесь в сводном виде отображается статистика мониторинга зон разделяемой памяти
для контекста `server` в `http`, формируемая на основе раздела API
[/status/http/server_zones/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-server-zones). Для каждой
зоны представлены следующие данные:
| `Зона` | Имя зоны |
|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Запросы` | Общее количество запросов, а также число запросов в секунду |
| `Ответы` | Количество ответов с разбиением по кодам статуса,
а также их общее количество |
| `Трафик` | Скорость исходящего и входящего трафика, а также общие объемы исходящего
и входящего трафика |
| `SSL` | Суммарные показатели количества: успешных SSL-рукопожатий; повторных использований SSL-сессий;
SSL-рукопожатий с истекшим таймаутом; неуспешных SSL-рукопожатий |
#### Раздел Зоны путей (Location)
Здесь в сводном виде отображается статистика мониторинга зон разделяемой памяти
для контекста `location` в `http`, формируемая на основе раздела API
[/status/http/location_zones/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-location-zones). Для
каждой зоны представлены следующие данные:
| `Зона` | Имя зоны |
|-----------|--------------------------------------------------------------------------------------------------|
| `Запросы` | Общее количество запросов, а также число запросов в секунду |
| `Ответы` | Количество ответов с разбиением по кодам статуса,
а также их общее количество |
| `Трафик` | Скорость исходящего и входящего трафика, а также общие объемы исходящего
и входящего трафика |
#### Раздел Зоны ограничения соединений (Limit Conn)
Здесь приведена статистика зон `limit_conn` в контексте `http`, формируемая
на основе раздела API [/status/http/limit_conns/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-limit-reqs). Для каждой зоны представлены следующие данные:
| `Зона` | Имя зоны |
|-------------|-----------------------------------------------------------------------------------------|
| `Передано` | Общее количество проксированных соединений |
| `Отклонено` | Общее количество сброшенных соединений |
| `Сброшено` | Общее количество соединений, сброшенных из-за переполнения хранилища
зоны |
| `Пропущено` | Общее количество соединений, переданных с нулевым или превосходящим 255
байт ключом |
#### Раздел Зоны ограничения запросов (Limit Req)
Здесь приведена статистика зон `limit_reqs` в контексте `http`, формируемая
на основе раздела API [/status/http/limit_reqs/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-limit-conns). Для
каждой зоны представлены следующие данные:
| `Зона` | Имя зоны |
|-------------|-----------------------------------------------------------------------------------------|
| `Передано` | Общее количество проксированных соединений |
| `Задержано` | Общее количество задержанных соединений |
| `Отклонено` | Общее количество сброшенных соединений |
| `Сброшено` | Общее количество соединений, сброшенных из-за переполнения хранилища
зоны |
| `Пропущено` | Общее количество соединений, переданных с нулевым или превосходящим 255
байт ключом |
### Вкладка HTTP-апстримы
#### WARNING
Требует задать директиву [zone](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone)
в блоке [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) в контексте `http`.
На этой вкладке в сводном виде отображается статистика мониторинга апстримов
контекста `http`, формируемая на основе раздела API
[/status/http/upstreams/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-upstreams).
В режиме отладки также отображается процент загрузки памяти.
- Кнопка `Показать список апстримов` переключает краткий список апстримов
с указанием числа проблемных апстримов и пиров.
- Переключатель `Только проблемные` переключает режим вывода статистики
по проблемным апстримам.
- Кнопка редактирования переключает интерфейс
`редактирования апстрима`.
- Раскрывающийся список с правой стороны таблицы каждого апстрима позволяет
отфильтровать серверы в определенном состоянии (`Активные`, `Проблемные`, `На проверке`,
`Недоступные`).
Для каждого апстрима, помимо имени и коэффициента использования зоны разделяемой
памяти, представлены следующие данные:
| `Сервер` | Имена, время простоя и веса серверов апстрима |
|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Запросы` | Общее количество и скорость обработки запросов |
| `Ответы` | Количество ответов с разбиением по кодам статуса |
| `Соединения` | Количество активных соединений и их максимальный предел, если он задан |
| `Трафик` | Скорость исходящего и входящего трафика, а также общие объемы исходящего
и входящего трафика |
| `Проверки сервера` | Количество неуспешных обращений к серверу и число раз, когда сервер
считался недоступным (объект `health` в API) |
| `Проверки работоспособности` | Общее количество проверок сервера, количество
неуспешных проверок, а также время последней проверки |
| `Время ответа` | Время от начала запроса до отправки первого байта ответа;
общее время от начала запроса до завершения отправки всего ответа
(объект `health` в API) |
#### Редактирование апстримов
В Angie PRO рядом с каждым апстримом есть кнопка редактирования; при нажатии
она выводит еще две кнопки:
| `Редактировать выбранные` | Редактирование выбранных серверов в составе апстрима. Позволяет
одновременно задать для всех следующие параметры: `Вес`,
максимальный предел соединений (`Max_conns`), максимальный предел
сбоев, переводящий сервер в недоступные (`Max_fails`), временное
окно подсчета сбоев для максимального предела сбоев
(`Fail_timeout`), состояние (`активный` – включен,
`недоступный` – выключен или `разгружаемый` – получает
только запросы сессий, привязанных ранее через `sticky`).
Также здесь можно удалить выбранные серверы.
 |
|-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Добавить сервер` | Добавление сервера в апстрим. Позволяет задать следующие параметры:
адрес, запасной сервер или нет, `Вес`, максимальный предел
соединений (`Max_conns`), максимальный предел сбоев, переводящий
сервер в недоступные (`Max_fails`), временное окно подсчета сбоев
(`Fail_timeout`), состояние (`активный` – включен,
`недоступный` – выключен или `разгружаемый` – получает
только запросы сессий, привязанных ранее через `sticky`).
 |
### Вкладка TCP/UDP-зоны
#### WARNING
Требует задать следующие директивы:
- `status_zone`
в контексте [server](https://angie.software//angie/docs/configuration/modules/http/index.md#status-zone) или [stream](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone);
- `limit_conn`
в контексте [server](https://angie.software//angie/docs/configuration/modules/http/http_api.md#limit-conn) или [stream](https://angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#s-limit-conn);
- [limit_conn_zone](https://angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#limit-conn-zone) в контексте `stream`.
Пример:
```nginx
stream {
# ...
limit_conn_zone $connection zone=limit-conn-stream:10m;
server {
# ...
limit_conn limit-conn-stream 1;
status_zone foo;
}
}
```
#### Раздел TCP/UDP-зоны
Здесь в сводном виде отображается статистика мониторинга зон разделяемой памяти
контекста `server` в `stream`, формируемая на основе раздела API
[/status/stream/server_zones/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-server-zones). Для каждой
зоны представлены следующие данные:
| `Зона` | Имя зоны |
|--------------|-------------------------------------------------------------------------------------------------------------------------------|
| `Соединения` | Текущее и общее количество соединений, а также число соединений в
секунду |
| `Сессии` | Количество сессий с разбиением по кодам статуса,
а также их общее число |
| `Трафик` | Скорость исходящего и входящего трафика, а также общие объемы исходящего
и входящего трафика |
| `SSL` | Суммарные показатели количества: успешных SSL-рукопожатий; неуспешных SSL-рукопожатий;
повторных использований SSL-сессий |
#### Раздел Зоны ограничения соединений (Limit Conn)
Здесь приведена статистика зон `limit_conn` в контексте
`stream`, формируемая на основе раздела API [/status/stream/limit_conns/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-limit-conns). Для каждой зоны представлены следующие данные:
| `Зона` | Имя зоны |
|-------------|-----------------------------------------------------------------------------------------|
| `Передано` | Общее количество проксированных соединений |
| `Отклонено` | Общее количество сброшенных соединений |
| `Сброшено` | Общее количество соединений, сброшенных из-за переполнения хранилища
зоны |
| `Пропущено` | Общее количество соединений, переданных с нулевым или превосходящим 255
байт ключом |
### Вкладка TCP/UDP-апстримы
#### WARNING
Требует задать директиву [zone](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone)
в блоке [upstream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) в контексте `stream`.
На этой вкладке в сводном виде отображается статистика мониторинга апстримов
контекста `stream`, формируемая на основе раздела API
[/status/stream/upstreams/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-upstreams).
В режиме отладки также отображается процент загрузки памяти.
- Кнопка `Показать список апстримов` переключает отображение краткого списка апстримов
с указанием числа проблемных апстримов и пиров.
- Переключатель `Только проблемные` включает и отключает режим вывода статистики
по проблемным апстримам.
- Кнопка редактирования открывает виджет
`редактирования апстрима`.
- Раскрывающийся список с правой стороны таблицы каждого апстрима позволяет
отфильтровать серверы в определенном состоянии (`Активные`,
`Проблемные`, `На проверке`, `Недоступные`).
Для каждого апстрима представлены следующие данные:
| `Сервер` | Имена, время простоя и веса серверов апстрима |
|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Соединения` | Количество активных соединений и их максимальный предел, если он задан |
| `Трафик` | Скорость исходящего и входящего трафика, а также общие объемы исходящего и входящего трафика |
| `Проверки сервера` | Количество неуспешных обращений к серверу и число раз, когда сервер
считался недоступным (объект `health` в API) |
| `Проверки работоспособности` | Общее количество проверок сервера, количество
неуспешных проверок, а также время последней проверки |
| `Время ответа` | Время, затраченное на установку соединения с бэкендом;
время от начала запроса до получения первого байта ответа;
общее время, прошедшее от начала запроса до получения последнего байта ответа
(объект `health` в API) |
#### Редактирование апстримов
В Angie PRO рядом с каждым апстримом есть кнопка редактирования; при нажатии
она выводит еще две кнопки:
| `Редактировать выбранные` | Редактирование выбранных серверов в составе апстрима. Позволяет
одновременно задать для всех следующие параметры: `Вес`,
максимальный предел соединений (`Max_conns`), максимальный предел
сбоев, переводящий сервер в недоступные (`Max_fails`), временное
окно подсчета сбоев для максимального предела сбоев
(`Fail_timeout`), состояние (`активный` – включен,
`недоступный` – выключен или `разгружаемый` – получает
только запросы сессий, привязанных ранее через `sticky`).
Также здесь можно удалить выбранные серверы.
 |
|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Добавить сервер` | Добавление сервера в апстрим. Позволяет задать следующие параметры:
адрес, запасной сервер или нет, `Вес`, максимальный предел
соединений (`Max_conns`), максимальный предел сбоев, переводящий
сервер в недоступные (`Max_fails`), временное окно подсчета сбоев
(`Fail_timeout`), состояние (`активный` – включен,
`недоступный` – выключен или `разгружаемый` – получает
только запросы сессий, привязанных ранее через `sticky`).
 |
### Вкладка Кэши
#### WARNING
Требует задать директиву [proxy_cache_path](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path)
в контексте `http`.
На этой вкладке в сводном виде отображается статистика мониторинга зон
`proxy_cache` контекста `http`, формируемая на основе раздела API
[/status/http/caches/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-caches). Для каждой зоны
представлены следующие данные:
| `Зона` | Имя зоны |
|-------------------------|---------------------------------------------------------------------------------------------------|
| `Состояние` | Состояние кэша: холодный (метаданные загружаются в память) или горячий
(метаданные загружены) |
| `Загрузка памяти` | Коэффициент использования памяти |
| `Макс. размер` | Максимальный объем памяти |
| `Использовано` | Использованный объем памяти |
| `Загрузка диска` | Коэффициент использования дисковой памяти |
| `Трафик` | Переданный из кэша, записанный в кэш и возвращенный в обход кэша трафик |
| `Коэффициент попадания` | Коэффициент попадания в кэш (отношение переданного из кэша трафика к
общему объему) |
Если для зоны включен [шардинг](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache), то она обозначена как
раскрывающийся список, в котором перечислены отдельные шарды:
| `Путь` | Путь шарда на диске |
|------------------|----------------------------------------------------------------------------------------------------|
| `Состояние` | Состояние шарда: холодный (метаданные загружаются в память) или горячий
(метаданные загружены) |
| `Макс. размер` | Максимальный объем памяти |
| `Использовано` | Использованный объем памяти |
| `Загрузка диска` | Коэффициент использования дисковой памяти |
### Вкладка Общие зоны
На этой вкладке в сводном виде отображается статистика мониторинга **всех** зон
разделяемой памяти для всех контекстов. Для каждой зоны представлены следующие
данные:
| `Зона` | Имя зоны |
|-------------------------------|-------------------------------------------|
| `Всего страниц памяти` | Общее количество страниц памяти |
| `Использовано страниц памяти` | Количество используемых страниц памяти |
| `Загрузка памяти` | Коэффициент использования памяти для зоны |
### Вкладка DNS-резолверы
#### WARNING
Требует задать директиву [resolver](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver)
в контексте `http`.
На этой вкладке в сводном виде отображается статистика запросов в зонах
разделяемой памяти DNS, формируемая на основе раздела API
[/status/resolvers/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-resolvers). Для каждой зоны представлены
следующие данные:
| `Зона` | Имя зоны |
|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Запросы` | Количество запросов типа A и AAAA, SRV, PTR |
| `Ответы` | Количество ответов с разделением по соответствующим кодам
(`Успешные`, `Ошибок формата`, `Сервер не завершил
запрос`, `Ошибок имени`, `Запрос не поддерживается`,
`Запрос отклонен` и прочих) |
### Виджет Настройки
Позволяет настроить общие параметры консоли:
- Частоту обновления данных. Значение по умолчанию — 1 сек.
- Пороговое соотношение статусов `4xx`. По достижении порога в
соответствующих разделах, посвященных ответам сервера, появляются "желтые"
предупреждения. Значение по умолчанию — 7%.
- Временное окно для вычисления соотношения успешных попаданий в кэш. Значение
по умолчанию — 300 сек.
- Порог учета ошибок для резолвера. По достижении указанного порога резолвер
станет "красным". Значение по умолчанию — 3%.
- Язык интерфейса консоли. Доступные варианты: английский (English) и русский.
По умолчанию язык консоли выбирается на основе локали, установленной в
браузере.
### Панель управления консолью
На всех вкладках в середине левой части страницы есть выдвигающаяся панель с
двумя кнопками . Верхняя приостанавливает и вновь запускает обновление
данных из API, а нижняя позволяет обновить данные вручную, когда обновление
приостановлено.
# https://angie.software/angie/docs/configuration/grafana.md
# Настройка панели Grafana
Чтобы настроить [панель для Angie](https://grafana.com/grafana/dashboards/20719-angie-dashboard/) в Grafana,
выполните следующие шаги:
1. Используя модуль [Prometheus](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus),
добавьте следующую директиву [include](https://angie.software//angie/docs/configuration/modules/core.md#include) в блок `http`
[файла конфигурации](https://angie.software//angie/docs/configuration/configfile.md#configfile):
```nginx
http {
include prometheus_all.conf;
# ...
}
```
Также добавьте соответствующую директиву [prometheus](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#id3)
внутри `location` в отдельном блоке `server`
cо специально отведенными для этой цели IP-адресом и портом, например:
```nginx
server {
listen 192.168.1.100:80;
location =/p8s {
prometheus all;
}
# ...
}
```
Они включают экспорт метрик Angie в формате Prometheus в конечной точке,
заданной в `location`.
2. Добавьте следующую конфигурацию в Prometheus,
указав IP-адрес и порт, заданные ранее в `server`:
```yaml
scrape_configs:
- job_name: "angie"
scrape_interval: 15s
metrics_path: "/p8s"
static_configs:
- targets: ["192.168.1.100:80"]
```
Она будет собирать метрики каждые 15 секунд,
используя настроенный на предыдущем шаге путь `/p8s`.
#### NOTE
Убедитесь, что значение глобального параметра `scrape_interval`
не превышает указанное здесь значение.
3. Импортируйте [панель для Angie](https://grafana.com/grafana/dashboards/20719-angie-dashboard/)
в Grafana.
# https://angie.software/angie/docs/configuration/custom-metrics.md
# Настройка пользовательских метрик
Angie может собирать пользовательские числовые метрики в разделяемой памяти и
выводить их через [API статистики](https://angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) по адресу
`/status/http/metric_zones/`. Это обеспечивает модуль
[Metric](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#http-metric).
## Шаги настройки
1. Создайте зону метрик в блоке `http`:
- [metric_zone](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-zone) создает зону с одной метрикой.
- [metric_complex_zone](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-complex-zone) создает зону с несколькими именованными метриками.
2. Обновляйте метрики при обработке запросов директивой [metric](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#id5).
Используйте пару `key=value` (оба — [комплексные значения](https://angie.software//angie/docs/configuration/configfile.md#syntax)),
и выберите этап обновления параметром `on=` (`request`,
`response` или `end`).
3. Откройте API через `location`:
```nginx
location /status/ {
api /status/http/metric_zones/;
}
```
## Пример
Подсчет запросов по хостам и вывод метрик через API:
```nginx
http {
metric_zone requests:128k count;
server {
listen 80;
location / {
metric requests $host=1;
}
location /status/ {
api /status/http/metric_zones/;
}
}
}
```
## Примечания
- При `expire=on` и переполнении памяти истекают самые давно неиспользуемые
записи. При `expire=off` новые обновления отбрасываются, а счетчик
`discarded` увеличивается.
- Если задан `discard_key`, метрики истекших записей агрегируются под этим
ключом в API.
- Длина ключей и значений ограничена 255 байт; длинные ключи усекутся в API.
- Пустое значение трактуется как `0`, а непустая строка без числа в начале
— как `1`.
# https://angie.software/angie/docs/troubleshooting.md
# Отладка
Если у вас возникла техническая проблема,
но нужное решение не удалось найти в других разделах,
задайте нам вопрос на [форуме сообщества](https://forum.angie.support/)
или в [Telegram-канале](https://t.me/angie_support).
Техническая поддержка для клиентов:
- [https://support.angie.software](https://support.angie.software)
- [support@angie.software](mailto:support@angie.software)
## Отладочный лог
Отладочный лог следует включать
перед самостоятельной диагностикой или по рекомендации технической поддержки.
Для этого запустите Angie, используя исполняемый файл с поддержкой отладки:
Linux
В [готовых пакетах](https://angie.software//angie/docs/installation/index.md#install-packages) для Linux
файл `angie-debug` собран с включенным отладочным логом:
```console
$ ls -l /usr/sbin/ | grep angie
lrwxrwxrwx 1 root root 13 Sep 21 18:58 angie -> angie-nodebug
-rwxr-xr-x 1 root root 1561224 Sep 21 18:58 angie-debug
-rwxr-xr-x 1 root root 1426056 Sep 21 18:58 angie-nodebug
```
Настройте запуск `angie-debug`:
```console
$ sudo ln -fs angie-debug /usr/sbin/angie
$ sudo angie -t && sudo service angie upgrade
```
Запустится [обновление исполняемого файла на лету](https://angie.software//angie/docs/configuration/runtime.md#service-upgrade).
Чтобы вернуться к обычному исполняемому файлу после окончания отладки:
```console
$ sudo ln -fs angie-nodebug /usr/sbin/angie
$ sudo angie -t && sudo service angie upgrade
```
FreeBSD
В [готовых пакетах](https://angie.software//angie/docs/installation/index.md#install-packages) для FreeBSD
файл `angie-debug` собран с включенным отладочным логом:
```console
$ ls -l /usr/local/sbin/ | grep angie
lrwxrwxrwx 1 root root 13 Sep 21 18:58 angie -> angie-nodebug
-rwxr-xr-x 1 root root 1561224 Sep 21 18:58 angie-debug
-rwxr-xr-x 1 root root 1426056 Sep 21 18:58 angie-nodebug
```
Настройте запуск `angie-debug`:
```console
$ sudo ln -fs angie-debug /usr/local/sbin/angie
$ sudo angie -t && sudo service angie upgrade
```
Запустится [обновление исполняемого файла на лету](https://angie.software//angie/docs/configuration/runtime.md#service-upgrade).
Чтобы вернуться к обычному исполняемому файлу после окончания отладки:
```console
$ sudo ln -fs angie-nodebug /usr/local/sbin/angie
$ sudo angie -t && sudo service angie upgrade
```
Docker
В [шаблонных Docker-образах](https://angie.software//angie/docs/installation/docker.md#docker-images)
можно переключиться на отладочную версию,
переопределив переменную окружения `ANGIE_BINARY`:
```console
$ docker run -it --rm -e ANGIE_BINARY="angie-debug" \
docker.angie.software/angie:templated
```
Сборка из исходников
При самостоятельной сборке Angie
нужно [включить отладку](https://angie.software//angie/docs/installation/sourcebuild.md#configure) перед сборкой:
```console
$ ./configure --with-debug ...
```
После установки команда **angie -V** позволяет убедиться,
что отладочный лог включен:
```console
$ angie -V
...
configure arguments: --with-debug ...
```
#### NOTE
Использование исполняемого файла с поддержкой отладки
может незначительно снизить производительность;
включение же отладочного лога может заметно снизить ее,
а также увеличить расход места на диске.
Чтобы включить отладочный лог,
задайте в конфигурации уровень `debug`
с помощью директивы [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log):
```nginx
error_log /path/to/log debug;
```
И перезагрузите конфигурацию:
```console
$ sudo angie -t && sudo service angie reload
```
В [шаблонных Docker-образах](https://angie.software//angie/docs/installation/docker.md#docker-images)
c включенным отладочным логом
также можно использовать переменную окружения
`ANGIE_ERROR_LOG_SEVERITY`:
```console
$ docker run -it --rm -e ANGIE_BINARY="angie-debug" \
-e ANGIE_ERROR_LOG_SEVERITY="debug" \
docker.angie.software/angie:templated
```
Если вернуться на исполняемый файл без поддержки отладки,
но оставить уровень `debug` в директиве [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log),
Angie будет добавлять записи в лог на уровне `info`.
Если переопределить [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log) в конфигурации,
но не указать в ней уровень `debug`, отладочный лог будет отключен.
Здесь переопределение лога на уровне [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server)
отключает отладочный лог для отдельного сервера:
```nginx
error_log /path/to/log debug;
http {
server {
error_log /path/to/log;
# ...
```
Во избежание этого уберите строку, переопределяющую [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log),
либо задайте в ней уровень `debug`:
```nginx
error_log /path/to/log debug;
http {
server {
error_log /path/to/log debug;
# ...
```
### Расположение директивы
Расположение директивы [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log)
влияет на полноту собираемой отладочной информации.
Директива, указанная на более низком уровне конфигурации
(например, внутри блока `server` или `location`),
заменяет настройки логирования, заданные на более высоком уровне
(например, на основном уровне конфигурации или внутри блока `http`).
### Отладочный лог отключен для конкретного сервера
Если глобально включен отладочный лог,
но для отдельного сервера [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log) указан без уровня `debug`,
то для этого сервера отладочная информация собираться не будет.
```nginx
error_log /var/log/angie/error.log debug; # Глобальный отладочный лог
http {
server {
listen 80;
server_name example.com;
error_log /var/log/angie/example.com.error.log;
# Отладочный лог для example.com отключен, в файле - уровень info
# ...
}
server {
listen 80;
server_name another.com;
# Для этого сервера будет использоваться глобальный отладочный лог
# ...
}
}
```
### Сохранение отладочного лога на уровне сервера
Чтобы сохранить сбор отладочной информации для конкретного сервера,
но направить ее в другой файл,
необходимо также указать уровень `debug`:
```nginx
error_log /var/log/angie/error.log debug; # Глобальный отладочный лог
http {
server {
listen 80;
server_name example.com;
error_log /var/log/angie/example.com.error.log debug;
# Отладочный лог для example.com включен, но пишется в отдельный файл
# ...
}
}
```
Таким образом, чтобы включить отладочный лог глобально,
но переопределить файл лога для отдельных блоков,
также укажите уровень `debug` в этих переопределениях.
Иначе, если в директиве [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log) не указан уровень логирования,
по умолчанию будет использоваться уровень `error`
и отладочная информация для этих блоков будет потеряна.
### Лог для отдельных адресов
Можно включить отладочный лог только для
[указанных клиентских адресов](https://angie.software//angie/docs/configuration/modules/core.md#debug-connection):
```nginx
error_log /path/to/log;
events {
debug_connection 192.168.1.1;
debug_connection 192.168.10.0/24;
}
```
### Кольцевой буфер в памяти
Отладочный лог можно записывать в кольцевой буфер в памяти:
```nginx
error_log memory:32m debug;
```
Запись в буфер в памяти на уровне `debug`
не будет существенно влиять на производительность даже при высоких нагрузках.
В этом случае лог можно извлечь при помощи GDB-скрипта, например:
```console
set $log = ngx_cycle->log
while $log->writer != ngx_log_memory_writer
set $log = $log->next
end
set $buf = (ngx_log_memory_buf_t *) $log->wdata
dump binary memory debug_log.txt $buf->start $buf->end
```
## Аварийные дампы памяти
Аварийные дампы памяти помогают в расследовании сбоев.
Прикладывайте их при [обращении в поддержку](#troubleshooting).
Для сборок из [наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
мы поддерживаем отладочные символы в специальных пакетах.
Они имеют те же имена, что и оригинальные пакеты,
с добавлением суффикса `-dbg`, например `angie-dbg`.
#### NOTE
В этом разделе предполагается,
что вы запускаете Angie от имени пользователя `root` (рекомендуется).
### Linux: systemd
Чтобы включить сохранение аварийных дампов при запуске Angie как службы **systemd**
(например, при [установке из пакетов](https://angie.software//angie/docs/installation/index.md#install-packages)),
измените [настройки службы](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Process%20Properties)
в файле `/lib/systemd/system/angie.service`:
```ini
[Service]
...
LimitCORE=infinity
LimitNOFILE=65535
```
Либо обновите [глобальные настройки](https://www.freedesktop.org/software/systemd/man/systemd-system.conf.html)
в файле `/etc/systemd/system.conf`:
```ini
[Manager]
...
DefaultLimitCORE=infinity
DefaultLimitNOFILE=65535
```
Затем перезагрузите конфигурацию службы и перезапустите Angie,
чтобы воспроизвести условия сбоя:
```console
$ sudo systemctl daemon-reload
$ sudo systemctl restart angie.service
```
После сбоя найдите файл аварийного дампа:
```console
$ sudo coredumpctl -1 # опционально
TIME PID UID GID SIG COREFILE EXE
--- |sampledateshort| 11:05:40 GMT 1157 0 0 11 present /usr/sbin/angie
$ sudo ls -al /var/lib/systemd/coredump/ # по умолчанию, см. также /etc/systemd/coredump.conf и /etc/systemd/coredump.conf.d/*.conf
...
-rw-r----- 1 root root 177662 Jul 27 11:05 core.angie.0.6135489c850b4fb4a74795ebbc1e382a.1157.1590577472000000.lz4
```
### Linux: ручная настройка
Проверьте [настройки аварийных дампов](https://man7.org/linux/man-pages/man5/limits.conf.5.html)
в файле `/etc/security/limits.conf`, при необходимости измените их:
```none
root soft core 0 # по умолчанию отключает аварийные дампы
root hard core unlimited # позволяет увеличить лимит размера
```
Затем увеличьте лимит размера аварийного дампа с помощью [ulimit](https://man7.org/linux/man-pages/man1/ulimit.1p.html),
после чего перезапустите Angie, чтобы воспроизвести условия сбоя:
```console
$ sudo ulimit -c unlimited
$ sudo cd <путь к установочному каталогу Angie>
$ sudo sbin/angie # или sbin/angie-debug
```
После сбоя найдите файл аварийного дампа:
```console
$ sudo ls -al <путь к рабочему каталогу Angie> # по умолчанию, см. /proc/sys/kernel/core_pattern
...
-rw-r----- 1 root root 177662 Jul 27 11:05 core.1157
```
### FreeBSD
Проверьте [настройки аварийных дампов](https://man.freebsd.org/cgi/man.cgi?query=sysctl.conf&sektion=5)
в файле `/etc/sysctl.conf`, при необходимости измените их:
```ini
kern.coredump=1 # должно быть равно 1
kern.corefile=/path/to/core/files/%N.core # нужен корректный путь
```
Либо обновите настройки во время выполнения:
```console
$ sudo sysctl kern.coredump=1
$ sudo sysctl kern.corefile=/path/to/core/files/%N.core
```
Затем перезапустите Angie, чтобы воспроизвести условия сбоя.
Если Angie установлен как служба:
```console
$ sudo service angie restart
```
Если Angie установлен вручную:
```console
$ sudo cd <путь к установочному каталогу Angie>
$ sudo sbin/angie
```
После сбоя найдите файл аварийного дампа:
```console
$ sudo ls -al <путь к файлам аварийных дампов>
...
-rw------- 1 root root 9912320 Jul 27 11:05 angie.core
```
# https://angie.software/angie/docs/development.md
# Разработка
Angie — проект с открытым исходным кодом,
поучаствовать в котором могут все.
## Исходный код
Клонировать исходный код Angie можно из наших открытых репозиториев:
[Mercurial](https://hg.angie.software/angie),
[Git](https://git.angie.software/web-server/angie).
## Стиль кода
Вносимые изменения должны сочетаться с остальным кодом Angie;
хорошей отправной точкой будут
[правила оформления кода](https://angie.software//angie/docs/developer_guide.md#developer-guide).
### Коммит-сообщения
Исторически коммит-лог ведется на английском языке.
Сообщение начинается с однострочной сводки о проделанной работе.
Она может иметь префикс, уже использованный в коммит-логе для этой части кода.
Сводка имеет длину до 67 символов включительно;
за ней может следовать пустая строка, после которой идут подробности.
В хорошем сообщении указаны причины изменения, что было сделано,
и каково положение дел сейчас:
```none
API: bad things removed, good things added.
As explained elsewhere[1], the original API was bad because stuff;
this change was introduced to improve that aspect locally.
Levels of goodness have been implemented to mitigate the badness;
this is now the preferred way to work. Also, the badness is gone.
[1] https://example.com
```
Детали, которые могли остаться незамеченными:
- Резюме кончается точкой и начинается с прописной (большой) буквы.
- Если использован префикс, то за ним следует строчная (маленькая) буква.
- Предложения в одной строке разделяются двойным пробелом.
## Финальные проверки
- Проверьте, что ваши изменения работают на *всех* целевых платформах.
- Запустите тесты на всех платформах, чтобы устранить возможность регрессии:
```sh
$ cd tests
$ prove .
```
Подробности см. в файле `tests/README`.
- Убедитесь, что вас устраивают [юридические условия](https://angie.software//legal/index.md#legal).
## Куда отправлять патчи
Чтобы отправить патч, создайте PR-запрос в нашем
[зеркале на GitHub](https://github.com/webserver-llc/angie/).
С вопросами и предложениями обращайтесь к разработчикам через
[GitHub Issues](https://github.com/webserver-llc/angie/issues).
# https://angie.software/angie/docs/developer_guide.md
# Руководство разработчика
## Правила оформления кода
Исходный код следует следующей структуре и соглашениям.
### Структура кода
* `auto` — Скрипты сборки
* `src`
* `core` — Базовые типы и функции — строки, массивы, журнал,
пул и т.д.
* `event` — Ядро событий
* `modules` — Модули уведомления о событиях:
`epoll`, `kqueue`, `select`
и т.д.
* `http` — Основной HTTP модуль и общий код
* `modules` — Другие HTTP модули
* `v2` — HTTP/2
* `mail` — Почтовые модули
* `os` — Платформо-зависимый код
* `unix`
* `win32`
* `stream` — Потоковые модули
### Включаемые файлы
Следующие два оператора `#include` должны присутствовать в
начале каждого файла Angie:
```c
#include
#include
```
В дополнение к этому, HTTP код должен включать
```c
#include
```
Почтовый код должен включать
```c
#include
```
Потоковый код должен включать
```c
#include
```
### Целые числа
Для общих целей код Angie использует два целочисленных типа,
`ngx_int_t` и `ngx_uint_t`, которые являются
typedef'ами для `intptr_t` и `uintptr_t`
соответственно.
### Общие коды возврата
Большинство функций в Angie возвращают следующие коды:
* `NGX_OK` — Операция выполнена успешно.
* `NGX_ERROR` — Операция завершилась неудачей.
* `NGX_AGAIN` — Операция не завершена; вызовите функцию снова.
* `NGX_DECLINED` — Операция отклонена, например, потому что она
отключена в конфигурации. Это никогда не является ошибкой.
* `NGX_BUSY` — Ресурс недоступен.
* `NGX_DONE` — Операция завершена или продолжена в другом месте.
Также используется как альтернативный код успеха.
* `NGX_ABORT` — Функция была прервана.
Также используется как альтернативный код ошибки.
### Обработка ошибок
Макрос `ngx_errno` возвращает последний код системной ошибки.
Он сопоставлен с `errno` на POSIX платформах и с
вызовом `GetLastError()` в Windows.
Макрос `ngx_socket_errno` возвращает последний номер ошибки
сокета.
Как и макрос `ngx_errno`, он сопоставлен с
`errno` на POSIX платформах.
Он сопоставлен с вызовом `WSAGetLastError()` в Windows.
Обращение к значениям `ngx_errno` или
`ngx_socket_errno` более одного раза подряд может вызвать
проблемы с производительностью.
Если значение ошибки может использоваться несколько раз, сохраните его в локальной переменной
типа `ngx_err_t`.
Для установки ошибок используйте макросы `ngx_set_errno(errno)` и
`ngx_set_socket_errno(errno)`.
Значения `ngx_errno` и
`ngx_socket_errno` могут быть переданы функциям журналирования
`ngx_log_error()` и `ngx_log_debugX()`, в
этом случае текст системной ошибки добавляется к сообщению журнала.
Пример использования `ngx_errno`:
```c
ngx_int_t
ngx_my_kill(ngx_pid_t pid, ngx_log_t *log, int signo)
{
ngx_err_t err;
if (kill(pid, signo) == -1) {
err = ngx_errno;
ngx_log_error(NGX_LOG_ALERT, log, err, "kill(%P, %d) failed", pid, signo);
if (err == NGX_ESRCH) {
return 2;
}
return 1;
}
return 0;
}
```
### Строки
#### Обзор
Для C строк Angie использует указатель на беззнаковый символьный тип
`u_char *`.
Строковый тип Angie `ngx_str_t` определен следующим образом:
```c
typedef struct {
size_t len;
u_char *data;
} ngx_str_t;
```
Поле `len` содержит длину строки, а
`data` содержит данные строки.
Строка, содержащаяся в `ngx_str_t`, может быть завершена
нулевым символом после `len` байт, а может и не быть.
В большинстве случаев она не завершена нулевым символом.
Однако в некоторых частях кода (например, при разборе конфигурации)
объекты `ngx_str_t` заведомо завершены нулевым символом, что
упрощает сравнение строк и облегчает передачу строк в
системные вызовы.
Операции со строками в Angie объявлены в
`src/core/ngx_string.h`.
Некоторые из них являются обертками вокруг стандартных функций C:
* `ngx_strcmp()`
* `ngx_strncmp()`
* `ngx_strstr()`
* `ngx_strlen()`
* `ngx_strchr()`
* `ngx_memcmp()`
* `ngx_memset()`
* `ngx_memcpy()`
* `ngx_memmove()`
Другие строковые функции специфичны для Angie:
* `ngx_memzero()` — Заполняет память нулями.
* `ngx_explicit_memzero()` — Делает то же самое, что и
`ngx_memzero()`, но этот вызов никогда не удаляется
оптимизацией компилятора по устранению мертвых записей.
Эта функция может использоваться для очистки чувствительных данных, таких как пароли и ключи.
* `ngx_cpymem()` — Делает то же самое, что и
`ngx_memcpy()`, но возвращает конечный адрес назначения.
Это удобно для последовательного добавления нескольких строк.
* `ngx_movemem()` — Делает то же самое, что и
`ngx_memmove()`, но возвращает конечный адрес назначения.
* `ngx_strlchr()` — Ищет символ в строке,
ограниченной двумя указателями.
Следующие функции выполняют преобразование регистра и сравнение:
* `ngx_tolower()`
* `ngx_toupper()`
* `ngx_strlow()`
* `ngx_strcasecmp()`
* `ngx_strncasecmp()`
Следующие макросы упрощают инициализацию строк:
* `ngx_string(text)` — статический инициализатор для типа
`ngx_str_t` из строкового литерала C
`text`
* `ngx_null_string` — статический инициализатор пустой строки для типа
`ngx_str_t`
* `ngx_str_set(str, text)` — инициализирует строку
`str` типа `ngx_str_t *` строковым литералом C
`text`
* `ngx_str_null(str)` — инициализирует строку `str`
типа `ngx_str_t *` пустой строкой
#### Форматирование
Следующие функции форматирования поддерживают специфичные для Angie типы:
* `ngx_sprintf(buf, fmt, ...)`
* `ngx_snprintf(buf, max, fmt, ...)`
* `ngx_slprintf(buf, last, fmt, ...)`
* `ngx_vslprintf(buf, last, fmt, args)`
* `ngx_vsnprintf(buf, max, fmt, args)`
Полный список опций форматирования, поддерживаемых этими функциями, находится
в `src/core/ngx_string.c`. Некоторые из них:
* `%O` — `off_t`
* `%T` — `time_t`
* `%z` — `ssize_t`
* `%i` — `ngx_int_t`
* `%p` — `void *`
* `%V` — `ngx_str_t *`
* `%s` — `u_char *` (завершенная нулевым символом)
* `%*s` — `size_t + u_char *`
Вы можете добавить префикс `u` к большинству типов, чтобы сделать их беззнаковыми.
Для преобразования вывода в шестнадцатеричный формат используйте `X` или `x`.
### Преобразование чисел
В Angie реализовано несколько функций для преобразования чисел.
Первые четыре преобразуют строку заданной длины в положительное целое число
указанного типа.
Они возвращают `NGX_ERROR` при ошибке.
* `ngx_atoi(line, n)` — `ngx_int_t`
* `ngx_atosz(line, n)` — `ssize_t`
* `ngx_atoof(line, n)` — `off_t`
* `ngx_atotm(line, n)` — `time_t`
Есть две дополнительные функции преобразования чисел.
Как и первые четыре, они возвращают `NGX_ERROR` при ошибке.
* `ngx_atofp(line, n, point)` — Преобразует число с фиксированной точкой
заданной длины в положительное целое число типа
`ngx_int_t`.
Результат сдвигается влево на `point` десятичных
позиций.
Ожидается, что строковое представление числа имеет не более
`point` дробных цифр.
Например, `ngx_atofp("10.5", 4, 2)` возвращает
`1050`.
* `ngx_hextoi(line, n)` — Преобразует шестнадцатеричное представление
положительного целого числа в `ngx_int_t`.
### Регулярные выражения
Интерфейс регулярных выражений в Angie является оберткой вокруг
библиотеки [PCRE](http://www.pcre.org).
Соответствующий заголовочный файл — `src/core/ngx_regex.h`.
Чтобы использовать регулярное выражение для сопоставления строк, его сначала нужно
скомпилировать, что обычно делается на этапе конфигурации.
Обратите внимание, что поскольку поддержка PCRE опциональна, весь код, использующий интерфейс, должен
быть защищен окружающим макросом `NGX_PCRE`:
```c
#if (NGX_PCRE)
ngx_regex_t *re;
ngx_regex_compile_t rc;
u_char errstr[NGX_MAX_CONF_ERRSTR];
ngx_str_t value = ngx_string("message (\\d\\d\\d).*Codeword is '(?\\w+)'");
ngx_memzero(&rc, sizeof(ngx_regex_compile_t));
rc.pattern = value;
rc.pool = cf->pool;
rc.err.len = NGX_MAX_CONF_ERRSTR;
rc.err.data = errstr;
/* rc.options can be set to NGX_REGEX_CASELESS */
if (ngx_regex_compile(&rc) != NGX_OK) {
ngx_conf_log_error(NGX_LOG_EMERG, cf, 0, "%V", &rc.err);
return NGX_CONF_ERROR;
}
re = rc.regex;
#endif
```
После успешной компиляции поля `captures` и
`named_captures` в структуре
`ngx_regex_compile_t` содержат количество всех
захватов и именованных захватов соответственно, найденных в регулярном выражении.
Скомпилированное регулярное выражение затем может использоваться для сопоставления со строками:
```c
ngx_int_t n;
int captures[(1 + rc.captures) * 3];
ngx_str_t input = ngx_string("This is message 123. Codeword is 'foobar'.");
n = ngx_regex_exec(re, &input, captures, (1 + rc.captures) * 3);
if (n >= 0) {
/* строка соответствует выражению */
} else if (n == NGX_REGEX_NO_MATCHED) {
/* совпадение не найдено */
} else {
/* какая-то ошибка */
ngx_log_error(NGX_LOG_ALERT, log, 0, ngx_regex_exec_n " failed: %i", n);
}
```
Аргументы `ngx_regex_exec()` — это скомпилированное регулярное
выражение `re`, строка для сопоставления `input`,
опциональный массив целых чисел для хранения любых найденных `captures`
и `size` массива.
Размер массива `captures` должен быть кратен трем,
как требует
[API PCRE](http://www.pcre.org/original/doc/html/pcreapi.html).
В примере размер вычисляется из общего количества захватов плюс
один для самой совпавшей строки.
Если есть совпадения, к захватам можно получить доступ следующим образом:
```c
u_char *p;
size_t size;
ngx_str_t name, value;
/* все захваты */
for (i = 0; i < n * 2; i += 2) {
value.data = input.data + captures[i];
value.len = captures[i + 1] - captures[i];
}
/* доступ к именованным захватам */
size = rc.name_size;
p = rc.names;
for (i = 0; i < rc.named_captures; i++, p += size) {
/* имя захвата */
name.data = &p[2];
name.len = ngx_strlen(name.data);
n = 2 * ((p[0] << 8) + p[1]);
/* захваченное значение */
value.data = &input.data[captures[n]];
value.len = captures[n + 1] - captures[n];
}
```
Функция `ngx_regex_exec_array()` принимает массив
элементов `ngx_regex_elt_t` (которые являются просто скомпилированными регулярными
выражениями с ассоциированными именами), строку для сопоставления и лог.
Функция применяет выражения из массива к строке до тех пор, пока
либо не найдено совпадение, либо не закончились выражения.
Возвращаемое значение — `NGX_OK` при наличии совпадения и
`NGX_DECLINED` в противном случае, или `NGX_ERROR`
в случае ошибки.
### Время
Структура `ngx_time_t` представляет время с тремя отдельными
типами для секунд, миллисекунд и смещения GMT:
```c
typedef struct {
time_t sec;
ngx_uint_t msec;
ngx_int_t gmtoff;
} ngx_time_t;
```
Структура `ngx_tm_t` является псевдонимом для
`struct tm` на UNIX-платформах и `SYSTEMTIME`
в Windows.
Для получения текущего времени обычно достаточно обратиться к одной из
доступных глобальных переменных, представляющих кэшированное значение времени в желаемом
формате.
Доступные строковые представления:
* `ngx_cached_err_log_time` — используется в записях журнала ошибок:
`"1970/09/28 12:00:00"`
* `ngx_cached_http_log_time` — используется в записях журнала доступа HTTP:
`"28/Sep/1970:12:00:00 +0600"`
* `ngx_cached_syslog_time` — используется в записях syslog:
`"Sep 28 12:00:00"`
* `ngx_cached_http_time` — используется в HTTP-заголовках:
`"Mon, 28 Sep 1970 06:00:00 GMT"`
* `ngx_cached_http_log_iso8601` — стандартный формат ISO 8601:
`"1970-09-28T12:00:00+06:00"`
Макросы `ngx_time()` и `ngx_timeofday()`
возвращают текущее значение времени в секундах и являются предпочтительным способом доступа
к кэшированному значению времени.
Для явного получения времени используйте `ngx_gettimeofday()`,
которая обновляет свой аргумент (указатель на
`struct timeval`).
Время всегда обновляется, когда Angie возвращается в цикл событий из системных
вызовов.
Для немедленного обновления времени вызовите `ngx_time_update()`,
или `ngx_time_sigsafe_update()`, если обновляете время в
контексте обработчика сигналов.
Следующие функции преобразуют `time_t` в указанное
разложенное представление времени.
Первая функция в каждой паре преобразует `time_t` в
`ngx_tm_t`, а вторая (с инфиксом `_libc_`)
в `struct tm`:
* `ngx_gmtime(), ngx_libc_gmtime()` — время, выраженное как UTC
* `ngx_localtime(), ngx_libc_localtime()` — время, выраженное
относительно местного часового пояса
Функция `ngx_http_time(buf, time)` возвращает строковое
представление, подходящее для использования в HTTP-заголовках (например,
`"Mon, 28 Sep 1970 06:00:00 GMT"`).
Функция `ngx_http_cookie_time(buf, time)` возвращает строковое
представление, подходящее для HTTP-куки (`"Thu, 31-Dec-37 23:55:55 GMT"`).
## Контейнеры
### Массив
Тип массива Angie `ngx_array_t` определяется следующим образом
```c
typedef struct {
void *elts;
ngx_uint_t nelts;
size_t size;
ngx_uint_t nalloc;
ngx_pool_t *pool;
} ngx_array_t;
```
Элементы массива доступны в поле `elts`.
Поле `nelts` содержит количество элементов.
Поле `size` содержит размер одного элемента и устанавливается
при инициализации массива.
Используйте вызов `ngx_array_create(pool, n, size)` для создания
массива в пуле, и вызов `ngx_array_init(array, pool, n, size)`
для инициализации объекта массива, который уже был выделен.
```c
ngx_array_t *a, b;
/* создать массив строк с предварительно выделенной памятью для 10 элементов */
a = ngx_array_create(pool, 10, sizeof(ngx_str_t));
/* инициализировать массив строк для 10 элементов */
ngx_array_init(&b, pool, 10, sizeof(ngx_str_t));
```
Используйте следующие функции для добавления элементов в массив:
* `ngx_array_push(a)` добавляет один элемент в конец и возвращает указатель
на него
* `ngx_array_push_n(a, n)` добавляет `n` элементов
в конец и возвращает указатель на первый из них
Если текущий выделенный объем памяти недостаточно велик для размещения
новых элементов, выделяется новый блок памяти и существующие элементы
копируются в него.
Новый блок памяти обычно в два раза больше существующего.
```c
s = ngx_array_push(a);
ss = ngx_array_push_n(&b, 3);
```
### Список
В Angie список представляет собой последовательность массивов, оптимизированную для вставки потенциально
большого количества элементов.
Тип списка `ngx_list_t` определяется следующим образом:
```c
typedef struct {
ngx_list_part_t *last;
ngx_list_part_t part;
size_t size;
ngx_uint_t nalloc;
ngx_pool_t *pool;
} ngx_list_t;
```
Фактические элементы хранятся в частях списка, которые определяются следующим образом:
```c
typedef struct ngx_list_part_s ngx_list_part_t;
struct ngx_list_part_s {
void *elts;
ngx_uint_t nelts;
ngx_list_part_t *next;
};
```
Перед использованием список должен быть инициализирован вызовом
`ngx_list_init(list, pool, n, size)` или создан вызовом
`ngx_list_create(pool, n, size)`.
Обе функции принимают в качестве аргументов размер одного элемента и количество
элементов на часть списка.
Для добавления элемента в список используйте функцию `ngx_list_push(list)`.
Для итерации по элементам обращайтесь напрямую к полям списка, как показано в
примере:
```c
ngx_str_t *v;
ngx_uint_t i;
ngx_list_t *list;
ngx_list_part_t *part;
list = ngx_list_create(pool, 100, sizeof(ngx_str_t));
if (list == NULL) { /* ошибка */ }
/* добавить элементы в список */
v = ngx_list_push(list);
if (v == NULL) { /* ошибка */ }
ngx_str_set(v, "foo");
v = ngx_list_push(list);
if (v == NULL) { /* ошибка */ }
ngx_str_set(v, "bar");
/* итерация по списку */
part = &list->part;
v = part->elts;
for (i = 0; /* void */; i++) {
if (i >= part->nelts) {
if (part->next == NULL) {
break;
}
part = part->next;
v = part->elts;
i = 0;
}
ngx_do_smth(&v[i]);
}
```
Списки в основном используются для входящих и исходящих HTTP-заголовков.
Списки не поддерживают удаление элементов.
Однако при необходимости элементы могут быть внутренне помечены как отсутствующие без фактического
удаления из списка.
Например, чтобы пометить исходящие HTTP-заголовки (которые хранятся как
объекты `ngx_table_elt_t`) как отсутствующие, установите поле
`hash` в `ngx_table_elt_t` в
ноль.
Элементы, помеченные таким образом, явно пропускаются при итерации
по заголовкам.
### Очередь
В Angie очередь представляет собой интрузивный двусвязный список, где каждый узел определяется как
следует:
```c
typedef struct ngx_queue_s ngx_queue_t;
struct ngx_queue_s {
ngx_queue_t *prev;
ngx_queue_t *next;
};
```
Головной узел очереди не связан с какими-либо данными.
Используйте вызов `ngx_queue_init(q)` для инициализации головы списка
перед использованием.
Очереди поддерживают следующие операции:
* `ngx_queue_insert_head(h, x)`,
`ngx_queue_insert_tail(h, x)` — вставить новый узел
* `ngx_queue_remove(x)` — удалить узел очереди
* `ngx_queue_split(h, q, n)` — разделить очередь в узле,
возвращая хвост очереди в отдельной очереди
* `ngx_queue_add(h, n)` — добавить вторую очередь к первой очереди
* `ngx_queue_head(h)`,
`ngx_queue_last(h)` — получить первый или последний узел очереди
* `ngx_queue_sentinel(h)` — получить объект-страж очереди для завершения
итерации
* `ngx_queue_data(q, type, link)` — получить ссылку на
начало структуры данных узла очереди, учитывая смещение поля очереди в
ней
Пример:
```c
typedef struct {
ngx_str_t value;
ngx_queue_t queue;
} ngx_foo_t;
ngx_foo_t *f;
ngx_queue_t values, *q;
ngx_queue_init(&values);
f = ngx_palloc(pool, sizeof(ngx_foo_t));
if (f == NULL) { /* ошибка */ }
ngx_str_set(&f->value, "foo");
ngx_queue_insert_tail(&values, &f->queue);
/* вставить больше узлов здесь */
for (q = ngx_queue_head(&values);
q != ngx_queue_sentinel(&values);
q = ngx_queue_next(q))
{
f = ngx_queue_data(q, ngx_foo_t, queue);
ngx_do_smth(&f->value);
}
```
### Красно-черное дерево
Заголовочный файл `src/core/ngx_rbtree.h` предоставляет доступ к
эффективной реализации красно-черных деревьев.
```c
typedef struct {
ngx_rbtree_t rbtree;
ngx_rbtree_node_t sentinel;
/* пользовательские данные для дерева */
} my_tree_t;
typedef struct {
ngx_rbtree_node_t rbnode;
/* пользовательские данные для узла */
foo_t val;
} my_node_t;
```
Для работы с деревом в целом необходимы два узла: корневой и сторожевой.
Обычно они добавляются в пользовательскую структуру, позволяя
организовать данные в дерево, в котором листья содержат ссылку на ваши
данные или встраивают их.
Для инициализации дерева:
```c
my_tree_t root;
ngx_rbtree_init(&root.rbtree, &root.sentinel, insert_value_function);
```
Для обхода дерева и вставки новых значений используются функции
`insert_value`.
Например, функция `ngx_str_rbtree_insert_value` работает
с типом `ngx_str_t`.
Ее аргументами являются указатели на корневой узел для вставки, вновь созданный
узел для добавления и сторожевой узел дерева.
```c
void ngx_str_rbtree_insert_value(ngx_rbtree_node_t *temp,
ngx_rbtree_node_t *node,
ngx_rbtree_node_t *sentinel)
```
Обход довольно прост и может быть продемонстрирован следующим
шаблоном функции поиска:
```c
my_node_t *
my_rbtree_lookup(ngx_rbtree_t *rbtree, foo_t *val, uint32_t hash)
{
ngx_int_t rc;
my_node_t *n;
ngx_rbtree_node_t *node, *sentinel;
node = rbtree->root;
sentinel = rbtree->sentinel;
while (node != sentinel) {
n = (my_node_t *) node;
if (hash != node->key) {
node = (hash < node->key) ? node->left : node->right;
continue;
}
rc = compare(val, node->val);
if (rc < 0) {
node = node->left;
continue;
}
if (rc > 0) {
node = node->right;
continue;
}
return n;
}
return NULL;
}
```
Функция `compare()` является классической функцией сравнения, которая
возвращает значение меньше, равное или больше нуля.
Для ускорения поиска и избежания сравнения пользовательских объектов, которые могут быть большими, используется целочисленное
поле хеша.
Для добавления узла в дерево выделите новый узел, инициализируйте его и вызовите
`ngx_rbtree_insert()`:
```c
my_node_t *my_node;
ngx_rbtree_node_t *node;
my_node = ngx_palloc(...);
init_custom_data(&my_node->val);
node = &my_node->rbnode;
node->key = create_key(my_node->val);
ngx_rbtree_insert(&root->rbtree, node);
```
Для удаления узла вызовите функцию `ngx_rbtree_delete()`:
```c
ngx_rbtree_delete(&root->rbtree, node);
```
### Хеш
Функции хеш-таблиц объявлены в `src/core/ngx_hash.h`.
Поддерживается как точное, так и шаблонное сопоставление.
Последнее требует дополнительной настройки и описано в отдельном разделе ниже.
Перед инициализацией хеша необходимо знать количество элементов, которые он будет
содержать, чтобы Angie мог построить его оптимально.
Два параметра, которые необходимо настроить: `max_size`
и `bucket_size`, как подробно описано в отдельном
[разделе](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
Обычно они настраиваются пользователем.
Настройки инициализации хеша хранятся в типе
`ngx_hash_init_t`, а сам хеш — в
`ngx_hash_t`:
```c
ngx_hash_t foo_hash;
ngx_hash_init_t hash;
hash.hash = &foo_hash;
hash.key = ngx_hash_key;
hash.max_size = 512;
hash.bucket_size = ngx_align(64, ngx_cacheline_size);
hash.name = "foo_hash";
hash.pool = cf->pool;
hash.temp_pool = cf->temp_pool;
```
`key` — это указатель на функцию, которая создает целочисленный ключ
хеша из строки.
Существуют две универсальные функции создания ключей:
`ngx_hash_key(data, len)` и
`ngx_hash_key_lc(data, len)`.
Последняя преобразует строку в символы нижнего регистра, поэтому переданная строка
должна быть доступна для записи.
Если это не так, передайте флаг `NGX_HASH_READONLY_KEY`
в функцию, инициализирующую массив ключей (см. ниже).
Ключи хеша хранятся в `ngx_hash_keys_arrays_t` и
инициализируются с помощью `ngx_hash_keys_array_init(arr, type)`.
Второй параметр (`type`) управляет количеством ресурсов,
предварительно выделенных для хеша, и может быть либо `NGX_HASH_SMALL`, либо
`NGX_HASH_LARGE`.
Последний подходит, если ожидается, что хеш будет содержать тысячи
элементов.
```c
ngx_hash_keys_arrays_t foo_keys;
foo_keys.pool = cf->pool;
foo_keys.temp_pool = cf->temp_pool;
ngx_hash_keys_array_init(&foo_keys, NGX_HASH_SMALL);
```
Для вставки ключей в массив ключей хеша используйте функцию
`ngx_hash_add_key(keys_array, key, value, flags)`:
```c
ngx_str_t k1 = ngx_string("key1");
ngx_str_t k2 = ngx_string("key2");
ngx_hash_add_key(&foo_keys, &k1, &my_data_ptr_1, NGX_HASH_READONLY_KEY);
ngx_hash_add_key(&foo_keys, &k2, &my_data_ptr_2, NGX_HASH_READONLY_KEY);
```
Для построения хеш-таблицы вызовите функцию
`ngx_hash_init(hinit, key_names, nelts)`:
```c
ngx_hash_init(&hash, foo_keys.keys.elts, foo_keys.keys.nelts);
```
Функция завершается неудачей, если параметры `max_size` или
`bucket_size` недостаточно велики.
Когда хеш построен, используйте функцию
`ngx_hash_find(hash, key, name, len)` для поиска
элементов:
```c
my_data_t *data;
ngx_uint_t key;
key = ngx_hash_key(k1.data, k1.len);
data = ngx_hash_find(&foo_hash, key, k1.data, k1.len);
if (data == NULL) {
/* ключ не найден */
}
```
#### Шаблонное сопоставление
Для создания хеша, работающего с шаблонами, используйте тип
`ngx_hash_combined_t`.
Он включает описанный выше тип хеша и имеет два дополнительных массива ключей:
`dns_wc_head` и `dns_wc_tail`.
Инициализация основных свойств аналогична обычному хешу:
```c
ngx_hash_init_t hash
ngx_hash_combined_t foo_hash;
hash.hash = &foo_hash.hash;
hash.key = ...;
```
Можно добавлять шаблонные ключи, используя флаг
`NGX_HASH_WILDCARD_KEY`:
```c
/* k1 = ".example.org"; */
/* k2 = "foo.*"; */
ngx_hash_add_key(&foo_keys, &k1, &data1, NGX_HASH_WILDCARD_KEY);
ngx_hash_add_key(&foo_keys, &k2, &data2, NGX_HASH_WILDCARD_KEY);
```
Функция распознает шаблоны и добавляет ключи в соответствующие массивы.
Обратитесь к документации модуля
[Map](https://angie.software//angie/docs/configuration/modules/http/http_map.md#http-map) для описания синтаксиса шаблонов и
алгоритма сопоставления.
В зависимости от содержимого добавленных ключей может потребоваться инициализировать до трех
массивов ключей: один для точного сопоставления (описанный выше) и два дополнительных для включения
сопоставления, начинающегося с начала или конца строки:
```c
if (foo_keys.dns_wc_head.nelts) {
ngx_qsort(foo_keys.dns_wc_head.elts,
(size_t) foo_keys.dns_wc_head.nelts,
sizeof(ngx_hash_key_t),
cmp_dns_wildcards);
hash.hash = NULL;
hash.temp_pool = pool;
if (ngx_hash_wildcard_init(&hash, foo_keys.dns_wc_head.elts,
foo_keys.dns_wc_head.nelts)
!= NGX_OK)
{
return NGX_ERROR;
}
foo_hash.wc_head = (ngx_hash_wildcard_t *) hash.hash;
}
```
Массив ключей необходимо отсортировать, а результаты инициализации должны быть добавлены
в комбинированный хеш.
Инициализация массива `dns_wc_tail` выполняется аналогично.
Поиск в комбинированном хеше обрабатывается функцией
`ngx_hash_find_combined(chash, key, name, len)`:
```c
/* key = "bar.example.org"; - будет соответствовать ".example.org" */
/* key = "foo.example.com"; - будет соответствовать "foo.*" */
hkey = ngx_hash_key(key.data, key.len);
res = ngx_hash_find_combined(&foo_hash, hkey, key.data, key.len);
```
## Управление памятью
### Куча
Для выделения памяти из системной кучи используйте следующие функции:
* `ngx_alloc(size, log)` — выделить память из системной кучи.
Это обертка вокруг `malloc()` с поддержкой логирования.
Ошибки выделения памяти и отладочная информация записываются в `log`.
* `ngx_calloc(size, log)` — выделить память из системной кучи
как `ngx_alloc()`, но заполнить память нулями после
выделения.
* `ngx_memalign(alignment, size, log)` — выделить выровненную память
из системной кучи.
Это обертка вокруг `posix_memalign()`
на тех платформах, которые предоставляют эту функцию.
В противном случае реализация возвращается к `ngx_alloc()`, которая
обеспечивает максимальное выравнивание.
* `ngx_free(p)` — освободить выделенную память.
Это обертка вокруг `free()`.
### Пул
Большинство выделений памяти в Angie выполняется в пулах.
Память, выделенная в пуле Angie, автоматически освобождается при уничтожении пула.
Это обеспечивает хорошую производительность выделения памяти и упрощает контроль памяти.
Пул внутренне выделяет объекты в непрерывных блоках памяти.
Когда блок заполняется, выделяется новый блок и добавляется в список блоков памяти пула.
Когда запрашиваемое выделение слишком велико для размещения в блоке, запрос
перенаправляется системному аллокатору, а
возвращенный указатель сохраняется в пуле для последующего освобождения.
Тип для пулов Angie — `ngx_pool_t`.
Поддерживаются следующие операции:
* `ngx_create_pool(size, log)` — создать пул с указанным
размером блока.
Возвращаемый объект пула также выделяется в пуле.
`size`
должен быть не менее `NGX_MIN_POOL_SIZE`
и кратным `NGX_POOL_ALIGNMENT`.
* `ngx_destroy_pool(pool)` — освободить всю память пула, включая
сам объект пула.
* `ngx_palloc(pool, size)` — выделить выровненную память из
указанного пула.
* `ngx_pcalloc(pool, size)` — выделить выровненную память
из указанного пула и заполнить ее нулями.
* `ngx_pnalloc(pool, size)` — выделить невыровненную память из
указанного пула.
В основном используется для выделения строк.
* `ngx_pfree(pool, p)` — освободить память, которая была ранее
выделена в указанном пуле.
Могут быть освобождены только выделения, которые являются результатом запросов, перенаправленных системному аллокатору.
```c
u_char *p;
ngx_str_t *s;
ngx_pool_t *pool;
pool = ngx_create_pool(1024, log);
if (pool == NULL) { /* error */ }
s = ngx_palloc(pool, sizeof(ngx_str_t));
if (s == NULL) { /* error */ }
ngx_str_set(s, "foo");
p = ngx_pnalloc(pool, 3);
if (p == NULL) { /* error */ }
ngx_memcpy(p, "foo", 3);
```
Звенья цепочек (`ngx_chain_t`) активно используются в Angie,
поэтому реализация пула Angie предоставляет способ их повторного использования.
Поле `chain` структуры `ngx_pool_t` хранит
список ранее выделенных звеньев, готовых к повторному использованию.
Для эффективного выделения звена цепочки в пуле используйте функцию
`ngx_alloc_chain_link(pool)`.
Эта функция ищет свободное звено цепочки в списке пула и выделяет новое
звено цепочки, если список пула пуст.
Для освобождения звена вызовите функцию `ngx_free_chain(pool, cl)`.
В пуле могут быть зарегистрированы обработчики очистки.
Обработчик очистки — это обратный вызов с аргументом, который вызывается при уничтожении пула.
Пул обычно связан с конкретным объектом Angie (например, HTTP-запросом) и
уничтожается, когда объект достигает конца своего жизненного цикла.
Регистрация очистки пула — это удобный способ освобождения ресурсов, закрытия
файловых дескрипторов или внесения окончательных изменений в общие данные, связанные с
основным объектом.
Для регистрации очистки пула вызовите
`ngx_pool_cleanup_add(pool, size)`, которая возвращает указатель
`ngx_pool_cleanup_t`, который должен быть
заполнен вызывающей стороной.
Используйте аргумент `size` для выделения контекста для обработчика
очистки.
```c
ngx_pool_cleanup_t *cln;
cln = ngx_pool_cleanup_add(pool, 0);
if (cln == NULL) { /* error */ }
cln->handler = ngx_my_cleanup;
cln->data = "foo";
...
static void
ngx_my_cleanup(void *data)
{
u_char *msg = data;
ngx_do_smth(msg);
}
```
### Разделяемая память
Разделяемая память используется Angie для совместного использования общих данных между процессами.
Функция `ngx_shared_memory_add(cf, name, size, tag)` добавляет
новую запись разделяемой памяти `ngx_shm_zone_t` в цикл.
Функция получает `name` и `size`
зоны.
Каждая разделяемая зона должна иметь уникальное имя.
Если запись разделяемой зоны с предоставленными `name` и
`tag` уже существует, существующая запись зоны используется повторно.
Функция завершается с ошибкой, если существующая запись с тем же именем имеет
другой тег.
Обычно адрес структуры модуля передается как
`tag`, что позволяет повторно использовать разделяемые зоны по имени в рамках
одного модуля Angie.
Структура записи разделяемой памяти `ngx_shm_zone_t` имеет
следующие поля:
* `init` — обратный вызов инициализации, вызываемый после того, как разделяемая зона
отображается на фактическую память
* `data` — контекст данных, используемый для передачи произвольных данных в
обратный вызов `init`
* `noreuse` — флаг, который отключает повторное использование разделяемой зоны из
старого цикла
* `tag` — тег разделяемой зоны
* `shm` — платформо-специфичный объект типа
`ngx_shm_t`, имеющий как минимум следующие поля:
* `addr` — адрес отображенной разделяемой памяти, изначально NULL
* `size` — размер разделяемой памяти
* `name` — имя разделяемой памяти
* `log` — журнал разделяемой памяти
* `exists` — флаг, указывающий, что разделяемая память была унаследована
от главного процесса (специфично для Windows)
Записи разделяемых зон отображаются на фактическую память в
`ngx_init_cycle()` после разбора конфигурации.
В POSIX-системах используется системный вызов `mmap()` для создания
разделяемого анонимного отображения.
В Windows используется пара `CreateFileMapping()`/
`MapViewOfFileEx()`.
Для выделения памяти в разделяемой памяти Angie предоставляет тип slab-пула
`ngx_slab_pool_t`.
Slab-пул для выделения памяти автоматически создается в каждой разделяемой зоне Angie.
Пул располагается в начале разделяемой зоны и доступен через
выражение `(ngx_slab_pool_t *) shm_zone->shm.addr`.
Для выделения памяти в разделяемой зоне вызовите либо
`ngx_slab_alloc(pool, size)`, либо
`ngx_slab_calloc(pool, size)`.
Для освобождения памяти вызовите `ngx_slab_free(pool, p)`.
Slab-пул разделяет всю разделяемую зону на страницы.
Каждая страница используется для выделения объектов одинакового размера.
Указанный размер должен быть степенью двойки и больше минимального размера в
8 байт.
Несоответствующие значения округляются вверх.
Битовая маска для каждой страницы отслеживает, какие блоки используются, а какие свободны для
выделения.
Для размеров больше половины страницы (что обычно составляет 2048 байт) выделение
выполняется целыми страницами за раз.
Для защиты данных в разделяемой памяти от одновременного доступа используйте мьютекс,
доступный в поле `mutex` структуры
`ngx_slab_pool_t`.
Мьютекс чаще всего используется slab-пулом при выделении и освобождении
памяти, но он может использоваться для защиты любых других пользовательских структур данных, выделенных
в разделяемой зоне.
Для блокировки или разблокировки мьютекса вызовите
`ngx_shmtx_lock(&shpool->mutex)` или
`ngx_shmtx_unlock(&shpool->mutex)` соответственно.
```c
ngx_str_t name;
ngx_foo_ctx_t *ctx;
ngx_shm_zone_t *shm_zone;
ngx_str_set(&name, "foo");
/* allocate shared zone context */
ctx = ngx_pcalloc(cf->pool, sizeof(ngx_foo_ctx_t));
if (ctx == NULL) {
/* error */
}
/* add an entry for 64k shared zone */
shm_zone = ngx_shared_memory_add(cf, &name, 65536, &ngx_foo_module);
if (shm_zone == NULL) {
/* error */
}
/* register init callback and context */
shm_zone->init = ngx_foo_init_zone;
shm_zone->data = ctx;
...
static ngx_int_t
ngx_foo_init_zone(ngx_shm_zone_t *shm_zone, void *data)
{
ngx_foo_ctx_t *octx = data;
size_t len;
ngx_foo_ctx_t *ctx;
ngx_slab_pool_t *shpool;
value = shm_zone->data;
if (octx) {
/* reusing a shared zone from old cycle */
ctx->value = octx->value;
return NGX_OK;
}
shpool = (ngx_slab_pool_t *) shm_zone->shm.addr;
if (shm_zone->shm.exists) {
/* initialize shared zone context in Windows Angie worker */
ctx->value = shpool->data;
return NGX_OK;
}
/* initialize shared zone */
ctx->value = ngx_slab_alloc(shpool, sizeof(ngx_uint_t));
if (ctx->value == NULL) {
return NGX_ERROR;
}
shpool->data = ctx->value;
return NGX_OK;
}
```
### Логирование
Для логирования Angie использует объекты `ngx_log_t`.
Логгер Angie поддерживает несколько типов вывода:
* stderr — логирование в стандартный поток ошибок (stderr)
* file — логирование в файл
* syslog — логирование в syslog
* memory — логирование во внутреннее хранилище памяти для целей разработки; к памяти
можно получить доступ позже с помощью отладчика
Экземпляр логгера может быть цепочкой логгеров, связанных друг с другом через
поле `next`.
В этом случае каждое сообщение записывается во все логгеры в цепочке.
Для каждого логгера уровень серьезности контролирует, какие сообщения записываются в
лог (логируются только события, назначенные этому уровню или выше).
Поддерживаются следующие уровни серьезности:
* `NGX_LOG_EMERG`
* `NGX_LOG_ALERT`
* `NGX_LOG_CRIT`
* `NGX_LOG_ERR`
* `NGX_LOG_WARN`
* `NGX_LOG_NOTICE`
* `NGX_LOG_INFO`
* `NGX_LOG_DEBUG`
Для отладочного логирования также проверяется маска отладки.
Маски отладки:
* `NGX_LOG_DEBUG_CORE`
* `NGX_LOG_DEBUG_ALLOC`
* `NGX_LOG_DEBUG_MUTEX`
* `NGX_LOG_DEBUG_EVENT`
* `NGX_LOG_DEBUG_HTTP`
* `NGX_LOG_DEBUG_MAIL`
* `NGX_LOG_DEBUG_STREAM`
Обычно логгеры создаются существующим кодом Angie из
директив `error_log` и доступны практически на каждом этапе
обработки в цикле, конфигурации, клиентском соединении и других объектах.
Nginx предоставляет следующие макросы логирования:
* `ngx_log_error(level, log, err, fmt, ...)` — логирование ошибок
* `ngx_log_debug0(level, log, err, fmt)`,
`ngx_log_debug1(level, log, err, fmt, arg1)` и т.д. — отладочное
логирование с поддержкой до восьми аргументов форматирования
Сообщение лога форматируется в буфере размером
`NGX_MAX_ERROR_STR` (в настоящее время 2048 байт) в стеке.
К сообщению добавляется префикс с уровнем серьезности, идентификатором процесса (PID), идентификатором соединения
(хранится в `log->connection`) и текстом системной ошибки.
Для неотладочных сообщений также вызывается `log->handler` для
добавления более специфичной информации к сообщению лога.
HTTP модуль устанавливает функцию `ngx_http_log_error()` как обработчик лога
для логирования адресов клиента и сервера, текущего действия (хранится в
`log->action`), строки запроса клиента, имени сервера и т.д.
```c
/* specify what is currently done */
log->action = "sending mp4 to client";
/* error and debug log */
ngx_log_error(NGX_LOG_INFO, c->log, 0, "client prematurely
closed connection");
ngx_log_debug2(NGX_LOG_DEBUG_HTTP, mp4->file.log, 0,
"mp4 start:%ui, length:%ui", mp4->start, mp4->length);
```
Приведенный выше пример приводит к записям лога, подобным этим:
```text
2016/09/16 22:08:52 [info] 17445#0: *1 client prematurely closed connection while
sending mp4 to client, client: 127.0.0.1, server: , request: "GET /file.mp4 HTTP/1.1"
2016/09/16 23:28:33 [debug] 22140#0: *1 mp4 start:0, length:10000
```
### Цикл
Объект цикла хранит контекст выполнения Angie, созданный из конкретной
конфигурации.
Его тип — `ngx_cycle_t`.
Текущий цикл ссылается на глобальную переменную `ngx_cycle` и
наследуется рабочими процессами Angie при их запуске.
Каждый раз при перезагрузке конфигурации Angie создается новый цикл из
новой конфигурации Angie; старый цикл обычно удаляется после успешного
создания нового.
Цикл создается функцией `ngx_init_cycle()`, которая
принимает предыдущий цикл в качестве аргумента.
Функция находит файл конфигурации предыдущего цикла и наследует как
можно больше ресурсов от предыдущего цикла.
Цикл-заполнитель, называемый "init cycle", создается при запуске Angie, затем
заменяется фактическим циклом, построенным из конфигурации.
Члены цикла включают:
* `pool` — пул цикла.
Создается для каждого нового цикла.
* `log` — журнал цикла.
Первоначально наследуется от старого цикла, устанавливается для указания на
`new_log` после чтения конфигурации.
* `new_log` — журнал цикла, созданный конфигурацией.
На него влияет директива `error_log` корневой области видимости.
* `connections`, `connection_n` —
массив соединений типа `ngx_connection_t`, созданный
модулем событий при инициализации каждого рабочего процесса Angie.
Директива `worker_connections` в конфигурации Angie
устанавливает количество соединений `connection_n`.
* `free_connections`,
`free_connection_n` — список и количество доступных в данный момент
соединений.
Если соединения недоступны, рабочий процесс Angie отказывается принимать новых клиентов
или подключаться к проксируемым серверам.
* `files`, `files_n` — массив для сопоставления файловых
дескрипторов с соединениями Angie.
Это сопоставление используется модулями событий, имеющими
флаг `NGX_USE_FD_EVENT` (в настоящее время это
`poll` и `devpoll`).
* `conf_ctx` — массив конфигураций основных модулей.
Конфигурации создаются и заполняются во время чтения файлов конфигурации Angie.
* `modules`, `modules_n` — массив модулей
типа `ngx_module_t`, как статических, так и динамических, загруженных
текущей конфигурацией.
* `listening` — массив объектов прослушивания типа
`ngx_listening_t`.
Объекты прослушивания обычно добавляются директивой `listen`
различных модулей, которые вызывают функцию
`ngx_create_listening()`.
Сокеты прослушивания создаются на основе объектов прослушивания.
* `paths` — массив путей типа `ngx_path_t`.
Пути добавляются вызовом функции `ngx_add_path()` из
модулей, которые собираются работать с определенными каталогами.
Эти каталоги создаются Angie после чтения конфигурации, если отсутствуют.
Более того, для каждого пути можно добавить два обработчика:
* загрузчик пути — выполняется только один раз в 60 секунд после запуска или перезагрузки
Angie.
Обычно загрузчик читает каталог и сохраняет данные в разделяемой памяти Angie.
Обработчик вызывается из выделенного процесса Angie "cache loader".
* менеджер пути — выполняется периодически.
Обычно менеджер удаляет старые файлы из каталога и обновляет память Angie
для отражения изменений.
Обработчик вызывается из выделенного процесса "cache manager".
* `open_files` — список объектов открытых файлов типа
`ngx_open_file_t`, которые создаются вызовом функции
`ngx_conf_open_file()`.
В настоящее время Angie использует такие открытые файлы для журналирования.
После чтения конфигурации Angie открывает все файлы в списке
`open_files` и сохраняет каждый файловый дескриптор в поле
`fd` объекта.
Файлы открываются в режиме добавления и создаются, если отсутствуют.
Файлы в списке переоткрываются рабочими процессами Angie при получении
сигнала переоткрытия (чаще всего `USR1`).
В этом случае дескриптор в поле `fd` изменяется на
новое значение.
* `shared_memory` — список зон разделяемой памяти, каждая добавляется
вызовом функции `ngx_shared_memory_add()`.
Разделяемые зоны отображаются на один и тот же диапазон адресов во всех процессах Angie и
используются для совместного использования общих данных, например, дерева HTTP-кеша в памяти.
### Буфер
Для операций ввода/вывода Angie предоставляет тип буфера
`ngx_buf_t`.
Обычно он используется для хранения данных, которые должны быть записаны в место назначения или прочитаны из
источника.
Буфер может ссылаться на данные в памяти или в файле, и технически
возможно, чтобы буфер ссылался на оба одновременно.
Память для буфера выделяется отдельно и не связана со структурой
буфера `ngx_buf_t`.
Структура `ngx_buf_t` имеет следующие поля:
* `start`, `end` — границы блока памяти,
выделенного для буфера.
* `pos`, `last` — границы буфера памяти;
обычно подмножество `start` ..
`end`.
* `file_pos`, `file_last` — границы файлового
буфера, выраженные как смещения от начала файла.
* `tag` — уникальное значение, используемое для различения буферов; создается
различными модулями Angie, обычно с целью повторного использования буфера.
* `file` — объект файла.
* `temporary` — флаг, указывающий, что буфер ссылается
на записываемую память.
* `memory` — флаг, указывающий, что буфер ссылается на память
только для чтения.
* `in_file` — флаг, указывающий, что буфер ссылается на данные
в файле.
* `flush` — флаг, указывающий, что все данные перед буфером
должны быть сброшены.
* `recycled` — флаг, указывающий, что буфер может быть повторно использован и
должен быть обработан как можно скорее.
* `sync` — флаг, указывающий, что буфер не несет данных или
специальный сигнал, такой как `flush` или `last_buf`.
По умолчанию Angie считает такие буферы условием ошибки, но этот флаг говорит
Angie пропустить проверку ошибки.
* `last_buf` — флаг, указывающий, что буфер является последним в
выводе.
* `last_in_chain` — флаг, указывающий, что больше нет буферов данных
в запросе или подзапросе.
* `shadow` — ссылка на другой ("теневой") буфер, связанный с
текущим буфером, обычно в том смысле, что буфер использует данные из
теневого буфера.
Когда буфер обрабатывается, теневой буфер обычно также помечается как
обработанный.
* `last_shadow` — флаг, указывающий, что буфер является последним,
который ссылается на конкретный теневой буфер.
* `temp_file` — флаг, указывающий, что буфер находится во временном
файле.
Для операций ввода и вывода буферы связываются в цепочки.
Цепочка — это последовательность звеньев цепи типа `ngx_chain_t`,
определенная следующим образом:
```c
typedef struct ngx_chain_s ngx_chain_t;
struct ngx_chain_s {
ngx_buf_t *buf;
ngx_chain_t *next;
};
```
Каждое звено цепи хранит ссылку на свой буфер и ссылку на следующее
звено цепи.
Пример использования буферов и цепочек:
```c
ngx_chain_t *
ngx_get_my_chain(ngx_pool_t *pool)
{
ngx_buf_t *b;
ngx_chain_t *out, *cl, **ll;
/* first buf */
cl = ngx_alloc_chain_link(pool);
if (cl == NULL) { /* error */ }
b = ngx_calloc_buf(pool);
if (b == NULL) { /* error */ }
b->start = (u_char *) "foo";
b->pos = b->start;
b->end = b->start + 3;
b->last = b->end;
b->memory = 1; /* read-only memory */
cl->buf = b;
out = cl;
ll = &cl->next;
/* second buf */
cl = ngx_alloc_chain_link(pool);
if (cl == NULL) { /* error */ }
b = ngx_create_temp_buf(pool, 3);
if (b == NULL) { /* error */ }
b->last = ngx_cpymem(b->last, "foo", 3);
cl->buf = b;
cl->next = NULL;
*ll = cl;
return out;
}
```
## Сетевое взаимодействие
### Соединение
Тип соединения `ngx_connection_t` является оберткой вокруг
дескриптора сокета.
Он включает следующие поля:
* `fd` — дескриптор сокета
* `data` — произвольный контекст соединения.
Обычно это указатель на объект более высокого уровня, построенный поверх
соединения, такой как HTTP-запрос или Stream-сессия.
* `read`, `write` — события чтения и записи для
соединения.
* `recv`, `send`,
`recv_chain`, `send_chain` — операции ввода-вывода
для соединения.
* `pool` — пул соединения.
* `log` — журнал соединения.
* `sockaddr`, `socklen`,
`addr_text` — адрес удаленного сокета в двоичной и текстовой формах.
* `local_sockaddr`, `local_socklen` — адрес
локального сокета в двоичной форме.
Изначально эти поля пусты.
Используйте функцию `ngx_connection_local_sockaddr()` для получения
адреса локального сокета.
* `proxy_protocol_addr`, `proxy_protocol_port`
— адрес и порт клиента по протоколу PROXY, если протокол PROXY включен для
соединения.
* `ssl` — SSL-контекст для соединения.
* `reusable` — флаг, указывающий, что соединение находится в состоянии,
которое делает его пригодным для повторного использования.
* `close` — флаг, указывающий, что соединение повторно используется
и должно быть закрыто.
Соединение Angie может прозрачно инкапсулировать SSL-слой.
В этом случае поле `ssl` соединения содержит указатель на
структуру `ngx_ssl_connection_t`, хранящую все SSL-связанные данные
для соединения, включая `SSL_CTX` и
`SSL`.
Обработчики `recv`, `send`,
`recv_chain` и `send_chain` также устанавливаются
в SSL-совместимые функции.
Директива `worker_connections` в конфигурации Angie
ограничивает количество соединений на один рабочий процесс Angie.
Все структуры соединений предварительно создаются при запуске рабочего процесса и сохраняются в
поле `connections` объекта цикла.
Для получения структуры соединения используйте функцию
`ngx_get_connection(s, log)`.
Она принимает в качестве аргумента `s` дескриптор сокета, который нужно
обернуть в структуру соединения.
Поскольку количество соединений на рабочий процесс ограничено, Angie предоставляет
способ захватывать соединения, которые в данный момент используются.
Для включения или отключения повторного использования соединения вызовите функцию
`ngx_reusable_connection(c, reusable)`.
Вызов `ngx_reusable_connection(c, 1)` устанавливает
флаг `reuse` в структуре соединения и вставляет
соединение в `reusable_connections_queue` цикла.
Когда `ngx_get_connection()` обнаруживает, что нет
доступных соединений в списке `free_connections` цикла,
она вызывает `ngx_drain_connections()` для освобождения
определенного количества повторно используемых соединений.
Для каждого такого соединения устанавливается флаг `close` и вызывается его обработчик чтения,
который должен освободить соединение, вызвав
`ngx_close_connection(c)` и сделать его доступным для повторного использования.
Для выхода из состояния, когда соединение может быть повторно использовано,
вызывается `ngx_reusable_connection(c, 0)`.
HTTP-соединения клиентов являются примером повторно используемых соединений в Angie; они
помечаются как повторно используемые до тех пор, пока первый байт запроса не будет получен от клиента.
## События
### Событие
Объект события `ngx_event_t` в Angie предоставляет механизм
для уведомления о том, что произошло определенное событие.
Поля в `ngx_event_t` включают:
* `data` — произвольный контекст события, используемый в обработчиках событий,
обычно как указатель на соединение, связанное с событием.
* `handler` — функция обратного вызова, которая будет вызвана при
наступлении события.
* `write` — флаг, указывающий на событие записи.
Отсутствие флага указывает на событие чтения.
* `active` — флаг, указывающий, что событие зарегистрировано для
получения уведомлений ввода-вывода, обычно от механизмов уведомления, таких как
`epoll`, `kqueue`, `poll`.
* `ready` — флаг, указывающий, что событие получило
уведомление ввода-вывода.
* `delayed` — флаг, указывающий, что ввод-вывод задержан из-за
ограничения скорости.
* `timer` — узел красно-черного дерева для вставки события в
дерево таймеров.
* `timer_set` — флаг, указывающий, что таймер события установлен и
еще не истек.
* `timedout` — флаг, указывающий, что таймер события истек.
* `eof` — флаг, указывающий, что произошел EOF при чтении данных.
* `pending_eof` — флаг, указывающий, что EOF ожидается на
сокете, даже если могут быть доступны некоторые данные перед ним.
Флаг доставляется через событие `EPOLLRDHUP`
`epoll` или
флаг `EV_EOF` `kqueue`.
* `error` — флаг, указывающий, что произошла ошибка во время
чтения (для события чтения) или записи (для события записи).
* `cancelable` — флаг события таймера, указывающий, что событие
должно игнорироваться при завершении работы рабочего процесса.
Корректное завершение работы рабочего процесса задерживается до тех пор, пока не останется запланированных
неотменяемых событий таймера.
* `posted` — флаг, указывающий, что событие помещено в очередь.
* `queue` — узел очереди для помещения события в очередь.
### События ввода-вывода
Каждое соединение, полученное путем вызова функции `ngx_get_connection()`,
имеет два прикрепленных события, `c->read` и
`c->write`, которые используются для получения уведомления о том, что
сокет готов для чтения или записи.
Все такие события работают в режиме Edge-Triggered, что означает, что они
запускают уведомления только при изменении состояния сокета.
Например, выполнение частичного чтения из сокета не заставляет Angie доставить
повторное уведомление о чтении до тех пор, пока в сокет не поступят новые данные.
Даже когда базовый механизм уведомлений ввода-вывода по существу является
Level-Triggered (`poll`, `select` и т.д.), Angie
преобразует уведомления в Edge-Triggered.
Чтобы сделать уведомления о событиях Angie согласованными во всех системах
уведомлений на разных платформах, функции
`ngx_handle_read_event(rev, flags)` и
`ngx_handle_write_event(wev, lowat)` должны вызываться после
обработки уведомления сокета ввода-вывода или вызова любых функций ввода-вывода
для этого сокета.
Обычно функции вызываются один раз в конце каждого обработчика события чтения
или записи.
### События таймера
Событие может быть настроено для отправки уведомления при истечении тайм-аута.
Таймер, используемый событиями, считает миллисекунды с некоторой неопределенной
точки в прошлом, усеченные до типа `ngx_msec_t`.
Его текущее значение можно получить из переменной `ngx_current_msec`.
Функция `ngx_add_timer(ev, timer)` устанавливает тайм-аут для
события, `ngx_del_timer(ev)` удаляет ранее установленный тайм-аут.
Глобальное красно-черное дерево тайм-аутов `ngx_event_timer_rbtree`
хранит все установленные в данный момент тайм-ауты.
Ключ в дереве имеет тип `ngx_msec_t` и представляет время,
когда происходит событие.
Структура дерева обеспечивает быстрые операции вставки и удаления, а также
доступ к ближайшим тайм-аутам, что Angie использует для определения того,
как долго ждать событий ввода-вывода и для истечения событий тайм-аута.
### Отложенные события
Событие может быть отложено, что означает, что его обработчик будет вызван
в какой-то момент позже в рамках текущей итерации цикла событий.
Откладывание событий является хорошей практикой для упрощения кода и избежания
переполнения стека.
Отложенные события хранятся в очереди отложенных событий.
Макрос `ngx_post_event(ev, q)` помещает событие
`ev` в очередь отложенных событий `q`.
Макрос `ngx_delete_posted_event(ev)` удаляет событие
`ev` из очереди, в которой оно в данный момент находится.
Обычно события помещаются в очередь `ngx_posted_events`,
которая обрабатывается поздно в цикле событий — после того, как все события
ввода-вывода и таймера уже обработаны.
Функция `ngx_event_process_posted()` вызывается для обработки
очереди событий.
Она вызывает обработчики событий до тех пор, пока очередь не станет пустой.
Это означает, что обработчик отложенного события может поместить больше событий
для обработки в рамках текущей итерации цикла событий.
Пример:
```c
void
ngx_my_connection_read(ngx_connection_t *c)
{
ngx_event_t *rev;
rev = c->read;
ngx_add_timer(rev, 1000);
rev->handler = ngx_my_read_handler;
ngx_my_read(rev);
}
void
ngx_my_read_handler(ngx_event_t *rev)
{
ssize_t n;
ngx_connection_t *c;
u_char buf[256];
if (rev->timedout) { /* timeout expired */ }
c = rev->data;
while (rev->ready) {
n = c->recv(c, buf, sizeof(buf));
if (n == NGX_AGAIN) {
break;
}
if (n == NGX_ERROR) { /* error */ }
/* process buf */
}
if (ngx_handle_read_event(rev, 0) != NGX_OK) { /* error */ }
}
```
### Цикл событий
За исключением главного процесса Angie, все процессы Angie выполняют операции ввода-вывода и поэтому имеют цикл событий.
(Главный процесс Angie вместо этого проводит большую часть времени в вызове
`sigsuspend()`, ожидая поступления сигналов.)
Цикл событий Angie реализован в функции
`ngx_process_events_and_timers()`, которая вызывается
многократно до завершения процесса.
Цикл событий имеет следующие этапы:
* Найти таймаут, который ближе всего к истечению, вызвав
`ngx_event_find_timer()`.
Эта функция находит самый левый узел в дереве таймеров и возвращает
количество миллисекунд до истечения узла.
* Обработать события ввода-вывода, вызвав обработчик, специфичный для механизма уведомления о событиях,
выбранного конфигурацией Angie.
Этот обработчик ожидает возникновения по крайней мере одного события ввода-вывода, но только до истечения следующего
таймаута.
Когда происходит событие чтения или записи, устанавливается флаг `ready`
и вызывается обработчик события.
Для Linux обычно используется обработчик `ngx_epoll_process_events()`,
который вызывает `epoll_wait()` для ожидания событий ввода-вывода.
* Истечь таймеры, вызвав `ngx_event_expire_timers()`.
Дерево таймеров обходится от самого левого элемента вправо до тех пор, пока не будет найден
неистекший таймаут.
Для каждого истекшего узла устанавливается флаг события `timedout`,
сбрасывается флаг `timer_set` и вызывается обработчик события.
* Обработать отложенные события, вызвав `ngx_event_process_posted()`.
Функция многократно удаляет первый элемент из очереди отложенных событий
и вызывает обработчик элемента, пока очередь не станет пустой.
Все процессы Angie также обрабатывают сигналы.
Обработчики сигналов только устанавливают глобальные переменные, которые проверяются после
вызова `ngx_process_events_and_timers()`.
### Процессы
В Angie существует несколько типов процессов.
Тип процесса хранится в глобальной переменной `ngx_process`
и является одним из следующих:
* `NGX_PROCESS_MASTER` — главный процесс, который читает
конфигурацию NGINX, создает циклы и запускает и контролирует дочерние процессы.
Он не выполняет никаких операций ввода-вывода и отвечает только на сигналы.
Его функция цикла — `ngx_master_process_cycle()`.
* `NGX_PROCESS_WORKER` — рабочий процесс, который обрабатывает
клиентские соединения.
Он запускается главным процессом и отвечает на его сигналы и команды канала.
Его функция цикла — `ngx_worker_process_cycle()`.
Может быть несколько рабочих процессов, как настроено директивой
`worker_processes`.
* `NGX_PROCESS_SINGLE` — единственный процесс, который существует только в
режиме `master_process off` и является единственным процессом, работающим в
этом режиме.
Он создает циклы (как делает главный процесс) и обрабатывает клиентские соединения
(как делает рабочий процесс).
Его функция цикла — `ngx_single_process_cycle()`.
* `NGX_PROCESS_HELPER` — вспомогательный процесс, из которых в настоящее время
существует два типа: менеджер кеша и загрузчик кеша.
Функция цикла для обоих —
`ngx_cache_manager_process_cycle()`.
Процессы Angie обрабатывают следующие сигналы:
* `NGX_SHUTDOWN_SIGNAL` (`SIGQUIT` в большинстве
систем) — корректное завершение работы.
При получении этого сигнала главный процесс отправляет сигнал завершения всем
дочерним процессам.
Когда дочерних процессов не остается, главный процесс уничтожает пул циклов и завершается.
Когда рабочий процесс получает этот сигнал, он закрывает все слушающие сокеты и
ожидает, пока не останется запланированных неотменяемых событий, затем уничтожает
пул циклов и завершается.
Когда менеджер кеша или процесс загрузчика кеша получает этот сигнал, он
завершается немедленно.
Переменная `ngx_quit` устанавливается в `1`, когда
процесс получает этот сигнал, и немедленно сбрасывается после обработки.
Переменная `ngx_exiting` устанавливается в `1`, пока
рабочий процесс находится в состоянии завершения.
* `NGX_TERMINATE_SIGNAL` (`SIGTERM` в большинстве
систем) — завершить.
При получении этого сигнала главный процесс отправляет сигнал завершения всем
дочерним процессам.
Если дочерний процесс не завершается в течение 1 секунды, главный процесс отправляет
сигнал `SIGKILL` для его принудительного завершения.
Когда дочерних процессов не остается, главный процесс уничтожает пул циклов и
завершается.
Когда рабочий процесс, процесс менеджера кеша или процесс загрузчика кеша
получает этот сигнал, он уничтожает пул циклов и завершается.
Переменная `ngx_terminate` устанавливается в `1`
при получении этого сигнала.
* `NGX_NOACCEPT_SIGNAL` (`SIGWINCH` в большинстве
систем) — завершить все рабочие и вспомогательные процессы.
При получении этого сигнала главный процесс завершает свои дочерние процессы.
Если ранее запущенный новый двоичный файл Angie завершается, дочерние процессы старого
главного процесса запускаются снова.
Когда рабочий процесс получает этот сигнал, он завершается в режиме отладки,
установленном директивой `debug_points`.
* `NGX_RECONFIGURE_SIGNAL` (`SIGHUP` в большинстве
систем) — перенастроить.
При получении этого сигнала главный процесс перечитывает конфигурацию и
создает новый цикл на ее основе.
Если новый цикл создан успешно, старый цикл удаляется и запускаются новые
дочерние процессы.
Тем временем старые дочерние процессы получают
сигнал `NGX_SHUTDOWN_SIGNAL`.
В однопроцессном режиме Angie создает новый цикл, но сохраняет старый до тех пор,
пока больше нет клиентов с активными соединениями, привязанными к нему.
Рабочие и вспомогательные процессы игнорируют этот сигнал.
* `NGX_REOPEN_SIGNAL` (`SIGUSR1` в большинстве
систем) — переоткрыть файлы.
Главный процесс отправляет этот сигнал рабочим процессам, которые переоткрывают все
`open_files`, связанные с циклом.
* `NGX_CHANGEBIN_SIGNAL` (`SIGUSR2` в большинстве
систем) — изменить исполняемый файл Angie.
Главный процесс запускает новый исполняемый файл Angie и передает ему список всех прослушиваемых
сокетов.
Список в текстовом формате, передаваемый в переменной окружения `"NGINX"`,
состоит из номеров дескрипторов, разделенных точками с запятой.
Новый исполняемый файл Angie читает переменную `"NGINX"` и добавляет
сокеты в свой цикл инициализации.
Другие процессы игнорируют этот сигнал.
Хотя все рабочие процессы Angie способны получать и правильно обрабатывать POSIX
сигналы, главный процесс не использует стандартный системный вызов `kill()`
для передачи сигналов рабочим процессам и вспомогательным процессам.
Вместо этого Angie использует межпроцессные пары сокетов, которые позволяют отправлять сообщения
между всеми процессами Angie.
В настоящее время, однако, сообщения отправляются только от главного процесса к его дочерним процессам.
Сообщения несут стандартные сигналы.
### Потоки
Возможно выгрузить в отдельный поток задачи, которые иначе
заблокировали бы рабочий процесс Angie.
Например, Angie можно настроить на использование потоков для выполнения
[файлового ввода-вывода](https://angie.software//angie/docs/configuration/modules/http/index.md#aio).
Другой случай использования — библиотека, которая не имеет асинхронного интерфейса
и поэтому не может быть нормально использована с Angie.
Имейте в виду, что интерфейс потоков является помощником для существующего
асинхронного подхода к обработке клиентских соединений, и ни в коем случае
не предназначен в качестве замены.
Для работы с синхронизацией доступны следующие обертки над
примитивами `pthreads`:
* `typedef pthread_mutex_t ngx_thread_mutex_t;`
* `ngx_int_t
ngx_thread_mutex_create(ngx_thread_mutex_t *mtx, ngx_log_t *log);`
* `ngx_int_t
ngx_thread_mutex_destroy(ngx_thread_mutex_t *mtx, ngx_log_t *log);`
* `ngx_int_t
ngx_thread_mutex_lock(ngx_thread_mutex_t *mtx, ngx_log_t *log);`
* `ngx_int_t
ngx_thread_mutex_unlock(ngx_thread_mutex_t *mtx, ngx_log_t *log);`
* `typedef pthread_cond_t ngx_thread_cond_t;`
* `ngx_int_t
ngx_thread_cond_create(ngx_thread_cond_t *cond, ngx_log_t *log);`
* `ngx_int_t
ngx_thread_cond_destroy(ngx_thread_cond_t *cond, ngx_log_t *log);`
* `ngx_int_t
ngx_thread_cond_signal(ngx_thread_cond_t *cond, ngx_log_t *log);`
* `ngx_int_t
ngx_thread_cond_wait(ngx_thread_cond_t *cond, ngx_thread_mutex_t *mtx,
ngx_log_t *log);`
Вместо создания нового потока для каждой задачи Angie реализует
стратегию [пула потоков](https://angie.software//angie/docs/configuration/modules/core.md#thread-pool).
Несколько пулов потоков могут быть настроены для разных целей
(например, для выполнения ввода-вывода на разных наборах дисков).
Каждый пул потоков создается при запуске и содержит ограниченное количество потоков,
которые обрабатывают очередь задач.
Когда задача завершена, вызывается предопределенный обработчик завершения.
Заголовочный файл `src/core/ngx_thread_pool.h` содержит
соответствующие определения:
```c
struct ngx_thread_task_s {
ngx_thread_task_t *next;
ngx_uint_t id;
void *ctx;
void (*handler)(void *data, ngx_log_t *log);
ngx_event_t event;
};
typedef struct ngx_thread_pool_s ngx_thread_pool_t;
ngx_thread_pool_t *ngx_thread_pool_add(ngx_conf_t *cf, ngx_str_t *name);
ngx_thread_pool_t *ngx_thread_pool_get(ngx_cycle_t *cycle, ngx_str_t *name);
ngx_thread_task_t *ngx_thread_task_alloc(ngx_pool_t *pool, size_t size);
ngx_int_t ngx_thread_task_post(ngx_thread_pool_t *tp, ngx_thread_task_t *task);
```
Во время конфигурации модуль, желающий использовать потоки, должен получить
ссылку на пул потоков, вызвав
`ngx_thread_pool_add(cf, name)`, которая либо создает
новый пул потоков с заданным `name`, либо возвращает ссылку
на пул с таким именем, если он уже существует.
Чтобы добавить `task` в очередь указанного пула потоков
`tp` во время выполнения, используйте функцию
`ngx_thread_task_post(tp, task)`.
Чтобы выполнить функцию в потоке, передайте параметры и настройте обработчик
завершения, используя структуру `ngx_thread_task_t`:
```c
typedef struct {
int foo;
} my_thread_ctx_t;
static void
my_thread_func(void *data, ngx_log_t *log)
{
my_thread_ctx_t *ctx = data;
/* this function is executed in a separate thread */
}
static void
my_thread_completion(ngx_event_t *ev)
{
my_thread_ctx_t *ctx = ev->data;
/* executed in Angie event loop */
}
ngx_int_t
my_task_offload(my_conf_t *conf)
{
my_thread_ctx_t *ctx;
ngx_thread_task_t *task;
task = ngx_thread_task_alloc(conf->pool, sizeof(my_thread_ctx_t));
if (task == NULL) {
return NGX_ERROR;
}
ctx = task->ctx;
ctx->foo = 42;
task->handler = my_thread_func;
task->event.handler = my_thread_completion;
task->event.data = ctx;
if (ngx_thread_task_post(conf->thread_pool, task) != NGX_OK) {
return NGX_ERROR;
}
return NGX_OK;
}
```
## Модули
### Добавление новых модулей
Каждый отдельный модуль Angie находится в отдельном каталоге, который содержит
как минимум два файла:
`config` и файл с исходным кодом модуля.
Файл `config` содержит всю информацию, необходимую Angie для
интеграции модуля, например:
```bash
ngx_module_type=CORE
ngx_module_name=ngx_foo_module
ngx_module_srcs="$ngx_addon_dir/ngx_foo_module.c"
. auto/module
ngx_addon_name=$ngx_module_name
```
Файл `config` является POSIX shell-скриптом, который может устанавливать
и обращаться к следующим переменным:
* `ngx_module_type` — тип модуля для сборки.
Возможные значения: `CORE`, `HTTP`,
`HTTP_FILTER`, `HTTP_INIT_FILTER`,
`HTTP_AUX_FILTER`, `MAIL`,
`STREAM` или `MISC`.
* `ngx_module_name` — имена модулей.
Для сборки нескольких модулей из набора исходных файлов укажите
разделенный пробелами список имен.
Первое имя указывает имя выходного двоичного файла для динамического модуля.
Имена в списке должны соответствовать именам, используемым в исходном коде.
* `ngx_addon_name` — имя модуля, как оно появляется в выводе
на консоли из скрипта configure.
* `ngx_module_srcs` — разделенный пробелами список исходных
файлов, используемых для компиляции модуля.
Переменная `$ngx_addon_dir` может использоваться для представления пути
к каталогу модуля.
* `ngx_module_incs` — пути включения, необходимые для сборки модуля
* `ngx_module_deps` — разделенный пробелами список зависимостей модуля.
Обычно это список заголовочных файлов.
* `ngx_module_libs` — разделенный пробелами список библиотек для
связывания с модулем.
Например, используйте `ngx_module_libs=-lpthread` для связывания
с библиотекой `libpthread`.
Следующие макросы могут использоваться для связывания с теми же библиотеками, что и
Angie:
`LIBXSLT`, `LIBGD`, `GEOIP`,
`PCRE`, `OPENSSL`, `MD5`,
`SHA1`, `ZLIB` и `PERL`.
* `ngx_module_link` — переменная, устанавливаемая системой сборки в
`DYNAMIC` для динамического модуля или `ADDON`
для статического модуля и используемая для определения различных действий
в зависимости от типа связывания.
* `ngx_module_order` — порядок загрузки модуля;
полезно для типов модулей `HTTP_FILTER` и
`HTTP_AUX_FILTER`.
Формат этой опции — разделенный пробелами список модулей.
Все модули в списке, следующие за именем текущего модуля, оказываются после него в
глобальном списке модулей, что устанавливает порядок инициализации модулей.
Для фильтрующих модулей более поздняя инициализация означает более раннее выполнение.
Следующие модули обычно используются в качестве ориентиров.
`ngx_http_copy_filter_module` читает данные для других
фильтрующих модулей и размещается ближе к концу списка, чтобы быть одним из
первых выполняемых.
`ngx_http_write_filter_module` записывает данные в
клиентский сокет и размещается ближе к началу списка, и выполняется последним.
По умолчанию фильтрующие модули размещаются перед
`ngx_http_copy_filter` в списке модулей, чтобы обработчик фильтра
выполнялся после обработчика фильтра копирования.
Для других типов модулей по умолчанию используется пустая строка.
Для компиляции модуля в Angie статически используйте аргумент
`--add-module=/path/to/module` для скрипта configure.
Для компиляции модуля для последующей динамической загрузки в Angie используйте аргумент
`--add-dynamic-module=/path/to/module`.
### Основные модули
Модули являются строительными блоками Angie, и большая часть его функциональности
реализована в виде модулей.
Исходный файл модуля должен содержать глобальную переменную типа
`ngx_module_t`, которая определена следующим образом:
```c
struct ngx_module_s {
/* private part is omitted */
void *ctx;
ngx_command_t *commands;
ngx_uint_t type;
ngx_int_t (*init_master)(ngx_log_t *log);
ngx_int_t (*init_module)(ngx_cycle_t *cycle);
ngx_int_t (*init_process)(ngx_cycle_t *cycle);
ngx_int_t (*init_thread)(ngx_cycle_t *cycle);
void (*exit_thread)(ngx_cycle_t *cycle);
void (*exit_process)(ngx_cycle_t *cycle);
void (*exit_master)(ngx_cycle_t *cycle);
/* stubs for future extensions are omitted */
};
```
Опущенная приватная часть включает версию модуля и подпись и
заполняется с использованием предопределенного макроса `NGX_MODULE_V1`.
Каждый модуль хранит свои приватные данные в поле `ctx`,
распознает директивы конфигурации, указанные в массиве
`commands`, и может быть вызван на определенных стадиях
жизненного цикла Angie.
Жизненный цикл модуля состоит из следующих событий:
* Обработчики директив конфигурации вызываются по мере их появления
в файлах конфигурации в контексте главного процесса.
* После успешного разбора конфигурации вызывается обработчик `init_module`
в контексте главного процесса.
Обработчик `init_module` вызывается в главном процессе каждый
раз при загрузке конфигурации.
* Главный процесс создает один или несколько рабочих процессов и
обработчик `init_process` вызывается в каждом из них.
* Когда рабочий процесс получает команду завершения или остановки от
главного процесса, он вызывает обработчик `exit_process`.
* Главный процесс вызывает обработчик `exit_master` перед
выходом.
Поскольку потоки используются в Angie только как вспомогательное средство ввода-вывода со своим
собственным API, обработчики `init_thread` и `exit_thread`
в настоящее время не вызываются.
Также отсутствует обработчик `init_master`, поскольку он был бы
ненужными накладными расходами.
Поле `type` модуля определяет точно, что хранится в поле
`ctx`.
Его значение является одним из следующих типов:
* `NGX_CORE_MODULE`
* `NGX_EVENT_MODULE`
* `NGX_HTTP_MODULE`
* `NGX_MAIL_MODULE`
* `NGX_STREAM_MODULE`
`NGX_CORE_MODULE` является наиболее базовым и, следовательно, наиболее
общим и низкоуровневым типом модуля.
Другие типы модулей реализованы поверх него и предоставляют более
удобный способ работы с соответствующими областями, такими как обработка событий или HTTP
запросов.
Набор основных модулей включает модули `ngx_core_module`,
`ngx_errlog_module`, `ngx_regex_module`,
`ngx_thread_pool_module` и
`ngx_openssl_module`.
HTTP модуль, stream модуль, mail модуль и модули событий также являются основными
модулями.
Контекст основного модуля определяется как:
```c
typedef struct {
ngx_str_t name;
void *(*create_conf)(ngx_cycle_t *cycle);
char *(*init_conf)(ngx_cycle_t *cycle, void *conf);
} ngx_core_module_t;
```
где `name` — это строка с именем модуля,
`create_conf` и `init_conf`
— указатели на функции, которые создают и инициализируют конфигурацию модуля
соответственно.
Для основных модулей Angie вызывает `create_conf` перед разбором
новой конфигурации и `init_conf` после успешного разбора всей конфигурации.
Типичная функция `create_conf` выделяет память для
конфигурации и устанавливает значения по умолчанию.
Например, упрощенный модуль под названием `ngx_foo_module` может
выглядеть следующим образом:
```c
/*
* Copyright (C) Author.
*/
#include
#include
typedef struct {
ngx_flag_t enable;
} ngx_foo_conf_t;
static void *ngx_foo_create_conf(ngx_cycle_t *cycle);
static char *ngx_foo_init_conf(ngx_cycle_t *cycle, void *conf);
static char *ngx_foo_enable(ngx_conf_t *cf, void *post, void *data);
static ngx_conf_post_t ngx_foo_enable_post = { ngx_foo_enable };
static ngx_command_t ngx_foo_commands[] = {
{ ngx_string("foo_enabled"),
NGX_MAIN_CONF|NGX_DIRECT_CONF|NGX_CONF_FLAG,
ngx_conf_set_flag_slot,
0,
offsetof(ngx_foo_conf_t, enable),
&ngx_foo_enable_post },
ngx_null_command
};
static ngx_core_module_t ngx_foo_module_ctx = {
ngx_string("foo"),
ngx_foo_create_conf,
ngx_foo_init_conf
};
ngx_module_t ngx_foo_module = {
NGX_MODULE_V1,
&ngx_foo_module_ctx, /* module context */
ngx_foo_commands, /* module directives */
NGX_CORE_MODULE, /* module type */
NULL, /* init master */
NULL, /* init module */
NULL, /* init process */
NULL, /* init thread */
NULL, /* exit thread */
NULL, /* exit process */
NULL, /* exit master */
NGX_MODULE_V1_PADDING
};
static void *
ngx_foo_create_conf(ngx_cycle_t *cycle)
{
ngx_foo_conf_t *fcf;
fcf = ngx_pcalloc(cycle->pool, sizeof(ngx_foo_conf_t));
if (fcf == NULL) {
return NULL;
}
fcf->enable = NGX_CONF_UNSET;
return fcf;
}
static char *
ngx_foo_init_conf(ngx_cycle_t *cycle, void *conf)
{
ngx_foo_conf_t *fcf = conf;
ngx_conf_init_value(fcf->enable, 0);
return NGX_CONF_OK;
}
static char *
ngx_foo_enable(ngx_conf_t *cf, void *post, void *data)
{
ngx_flag_t *fp = data;
if (*fp == 0) {
return NGX_CONF_OK;
}
ngx_log_error(NGX_LOG_NOTICE, cf->log, 0, "Foo Module is enabled");
return NGX_CONF_OK;
}
```
### Директивы конфигурации
Тип `ngx_command_t` определяет одну директиву конфигурации.
Каждый модуль, который поддерживает конфигурацию, предоставляет массив таких структур,
которые описывают, как обрабатывать аргументы и какие обработчики вызывать:
```c
typedef struct ngx_command_s ngx_command_t;
struct ngx_command_s {
ngx_str_t name;
ngx_uint_t type;
char *(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
ngx_uint_t conf;
ngx_uint_t offset;
void *post;
};
```
Завершите массив специальным значением `ngx_null_command`.
`name` — это имя директивы, как оно появляется
в конфигурационном файле, например "worker_processes" или "listen".
`type` — это битовое поле флагов, которое определяет количество
аргументов, принимаемых директивой, ее тип и контекст, в котором она появляется.
Флаги:
* `NGX_CONF_NOARGS` — Директива не принимает аргументов.
* `NGX_CONF_1MORE` — Директива принимает один или более аргументов.
* `NGX_CONF_2MORE` — Директива принимает два или более аргументов.
* `NGX_CONF_TAKE1` .. `NGX_CONF_TAKE7` —
Директива принимает точно указанное количество аргументов.
* `NGX_CONF_TAKE12`, `NGX_CONF_TAKE13`,
`NGX_CONF_TAKE23`, `NGX_CONF_TAKE123`,
`NGX_CONF_TAKE1234` — Директива может принимать разное количество
аргументов.
Варианты ограничены указанными числами.
Например, `NGX_CONF_TAKE12` означает, что она принимает один или два
аргумента.
Флаги для типов директив:
* `NGX_CONF_BLOCK` — Директива является блоком, то есть она может
содержать другие директивы внутри своих открывающих и закрывающих скобок, или даже
реализовать собственный парсер для обработки содержимого внутри.
* `NGX_CONF_FLAG` — Директива принимает логическое значение, либо
`on`, либо `off`.
Контекст директивы определяет, где она может появляться в конфигурации:
* `NGX_MAIN_CONF` — В контексте верхнего уровня.
* `NGX_HTTP_MAIN_CONF` — В блоке `http`.
* `NGX_HTTP_SRV_CONF` — В блоке `server`
внутри блока `http`.
* `NGX_HTTP_LOC_CONF` — В блоке `location`
внутри блока `http`.
* `NGX_HTTP_UPS_CONF` — В блоке `upstream`
внутри блока `http`.
* `NGX_HTTP_SIF_CONF` — В блоке `if` внутри
блока `server` в блоке `http`.
* `NGX_HTTP_LIF_CONF` — В блоке `if` внутри
блока `location` в блоке `http`.
* `NGX_HTTP_LMT_CONF` — В блоке `limit_except`
внутри блока `http`.
* `NGX_STREAM_MAIN_CONF` — В блоке `stream`.
* `NGX_STREAM_SRV_CONF` — В блоке `server`
внутри блока `stream`.
* `NGX_STREAM_UPS_CONF` — В блоке `upstream`
внутри блока `stream`.
* `NGX_MAIL_MAIN_CONF` — В блоке `mail`.
* `NGX_MAIL_SRV_CONF` — В блоке `server`
внутри блока `mail`.
* `NGX_EVENT_CONF` — В блоке `events`.
* `NGX_DIRECT_CONF` — Используется модулями, которые не
создают иерархию контекстов и имеют только одну глобальную конфигурацию.
Эта конфигурация передается обработчику как аргумент `conf`.
Парсер конфигурации использует эти флаги для выдачи ошибки в случае
неправильно размещенной директивы и вызывает обработчики директив, снабженные соответствующим
указателем конфигурации, так что одни и те же директивы в разных местах могут
сохранять свои значения в отдельных местах.
Поле `set` определяет обработчик, который обрабатывает директиву
и сохраняет разобранные значения в соответствующую конфигурацию.
Существует ряд функций, которые выполняют общие преобразования:
* `ngx_conf_set_flag_slot` — Преобразует литеральные строки
`on` и `off` в значение
`ngx_flag_t` со значениями 1 или 0, соответственно.
* `ngx_conf_set_str_slot` — Сохраняет строку как значение типа
`ngx_str_t`.
* `ngx_conf_set_str_array_slot` — Добавляет значение в массив
`ngx_array_t` строк `ngx_str_t`.
Массив создается, если еще не существует.
* `ngx_conf_set_keyval_slot` — Добавляет пару ключ-значение в
массив `ngx_array_t` пар ключ-значение
`ngx_keyval_t`.
Первая строка становится ключом, а вторая — значением.
Массив создается, если еще не существует.
* `ngx_conf_set_num_slot` — Преобразует аргумент директивы
в значение `ngx_int_t`.
* `ngx_conf_set_size_slot` — Преобразует
[размер](https://angie.software//angie/docs/configuration/configfile.md#syntax) в значение `size_t`,
выраженное в байтах.
* `ngx_conf_set_off_slot` — Преобразует
[смещение](https://angie.software//angie/docs/configuration/configfile.md#syntax) в значение `off_t`,
выраженное в байтах.
* `ngx_conf_set_msec_slot` — Преобразует
[время](https://angie.software//angie/docs/configuration/configfile.md#syntax) в значение `ngx_msec_t`,
выраженное в миллисекундах.
* `ngx_conf_set_sec_slot` — Преобразует
[время](https://angie.software//angie/docs/configuration/configfile.md#syntax) в значение `time_t`,
выраженное в секундах.
* `ngx_conf_set_bufs_slot` — Преобразует два предоставленных аргумента
в объект `ngx_bufs_t`, который содержит количество и
[размер](https://angie.software//angie/docs/configuration/configfile.md#syntax) буферов.
* `ngx_conf_set_enum_slot` — Преобразует предоставленный аргумент
в значение `ngx_uint_t`.
Завершающийся нулем массив `ngx_conf_enum_t`, переданный в поле
`post`, определяет допустимые строки и соответствующие
целочисленные значения.
* `ngx_conf_set_bitmask_slot` — Преобразует предоставленные аргументы
в значение `ngx_uint_t`.
Значения масок для каждого аргумента объединяются операцией ИЛИ, создавая результат.
Завершающийся нулем массив `ngx_conf_bitmask_t`, переданный в поле
`post`, определяет допустимые строки и соответствующие
значения масок.
* `ngx_conf_set_path_slot` — Преобразует предоставленные аргументы в значение
`ngx_path_t` и выполняет все необходимые инициализации.
Подробности см. в документации для директивы
[proxy_temp_path](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-temp-path).
* `ngx_conf_set_access_slot` — Преобразует предоставленные аргументы в маску
прав доступа к файлу.
Подробности см. в документации для директивы
[proxy_store_access](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-store-access).
Поле `conf` определяет, какая структура конфигурации
передается обработчику директивы.
Основные модули имеют только глобальную конфигурацию и устанавливают
флаг `NGX_DIRECT_CONF` для доступа к ней.
Модули, такие как HTTP, Stream или Mail, создают иерархии конфигураций.
Например, конфигурация модуля создается для областей `server`,
`location` и `if`.
* `NGX_HTTP_MAIN_CONF_OFFSET` — Конфигурация для блока
`http`.
* `NGX_HTTP_SRV_CONF_OFFSET` — Конфигурация для блока
`server` внутри блока `http`.
* `NGX_HTTP_LOC_CONF_OFFSET` — Конфигурация для блока
`location` внутри блока `http`.
* `NGX_STREAM_MAIN_CONF_OFFSET` — Конфигурация для блока
`stream`.
* `NGX_STREAM_SRV_CONF_OFFSET` — Конфигурация для блока
`server` внутри блока `stream`.
* `NGX_MAIL_MAIN_CONF_OFFSET` — Конфигурация для блока
`mail`.
* `NGX_MAIL_SRV_CONF_OFFSET` — Конфигурация для блока
`server` внутри блока `mail`.
Поле `offset` определяет смещение поля в структуре конфигурации модуля,
которое содержит значения для данной конкретной директивы.
Типичное использование — применение макроса `offsetof()`.
Поле `post` имеет две цели: оно может использоваться для определения
обработчика, который будет вызван после завершения основного обработчика, или для передачи
дополнительных данных основному обработчику.
В первом случае структура `ngx_conf_post_t` должна быть
инициализирована указателем на обработчик, например:
```c
static char *ngx_do_foo(ngx_conf_t *cf, void *post, void *data);
static ngx_conf_post_t ngx_foo_post = { ngx_do_foo };
```
Аргумент `post` является самим объектом `ngx_conf_post_t`,
а `data` — это указатель на значение,
преобразованное из аргументов основным обработчиком с соответствующим типом.
## HTTP
### Соединение
Каждое HTTP-соединение клиента проходит через следующие этапы:
* `ngx_event_accept()` принимает TCP-соединение клиента.
Этот обработчик вызывается в ответ на уведомление о чтении на слушающем сокете.
На этом этапе создается новый объект `ngx_connection_t`
для обертывания вновь принятого клиентского сокета.
Каждый слушатель Angie предоставляет обработчик для передачи нового объекта соединения.
Для HTTP-соединений это `ngx_http_init_connection(c)`.
* `ngx_http_init_connection()` выполняет раннюю инициализацию
HTTP-соединения.
На этом этапе создается объект `ngx_http_connection_t` для
соединения, и его ссылка сохраняется в поле `data` соединения.
Позже он будет заменен объектом HTTP-запроса.
На этом этапе также запускается парсер протокола PROXY и SSL-рукопожатие.
* `ngx_http_wait_request_handler()` обработчик события чтения
вызывается, когда данные доступны на клиентском сокете.
На этом этапе создается объект HTTP-запроса `ngx_http_request_t`
и устанавливается в поле `data` соединения.
* `ngx_http_process_request_line()` обработчик события чтения
читает строку запроса клиента.
Обработчик устанавливается `ngx_http_wait_request_handler()`.
Данные читаются в `buffer` соединения.
Размер буфера изначально устанавливается директивой
[client_header_buffer_size](https://angie.software//angie/docs/configuration/modules/http/index.md#client-header-buffer-size).
Предполагается, что весь заголовок клиента поместится в буфер.
Если начального размера недостаточно, выделяется больший буфер
с емкостью, установленной директивой [large_client_header_buffers](https://angie.software//angie/docs/configuration/modules/http/index.md#large-client-header-buffers).
* `ngx_http_process_request_headers()` обработчик события чтения
устанавливается после `ngx_http_process_request_line()` для чтения
заголовка запроса клиента.
* `ngx_http_core_run_phases()` вызывается, когда заголовок запроса
полностью прочитан и разобран.
Эта функция запускает фазы запроса от
`NGX_HTTP_POST_READ_PHASE` до
`NGX_HTTP_CONTENT_PHASE`.
Последняя фаза предназначена для генерации ответа и передачи его по цепочке фильтров.
Ответ не обязательно отправляется клиенту на этой фазе.
Он может остаться в буфере и быть отправленным на этапе финализации.
* `ngx_http_finalize_request()` обычно вызывается, когда
запрос сгенерировал весь вывод или произвел ошибку.
В последнем случае ищется соответствующая страница ошибки и используется как ответ.
Если ответ не полностью отправлен клиенту к этому моменту,
активируется HTTP-писатель `ngx_http_writer()` для завершения
отправки оставшихся данных.
* `ngx_http_finalize_connection()` вызывается, когда полный
ответ отправлен клиенту и запрос может быть уничтожен.
Если включена функция keepalive клиентского соединения,
вызывается `ngx_http_set_keepalive()`, которая уничтожает
текущий запрос и ожидает следующий запрос на соединении.
В противном случае `ngx_http_close_request()` уничтожает
как запрос, так и соединение.
### Запрос
Для каждого HTTP-запроса клиента создается объект `ngx_http_request_t`.
Некоторые поля этого объекта:
* `connection` — Указатель на объект клиентского соединения
`ngx_connection_t`.
Несколько запросов могут ссылаться на один и тот же объект соединения одновременно -
один основной запрос и его подзапросы.
После удаления запроса на том же соединении может быть создан новый запрос.
Обратите внимание, что для HTTP-соединений поле `data`
объекта `ngx_connection_t` указывает обратно на запрос.
Такие запросы называются активными, в отличие от других запросов, привязанных к соединению.
Активный запрос используется для обработки событий клиентского соединения и может
выводить свой ответ клиенту.
Обычно каждый запрос становится активным в какой-то момент, чтобы отправить свой вывод.
* `ctx` — Массив контекстов HTTP-модулей.
Каждый модуль типа `NGX_HTTP_MODULE` может хранить любое значение
(обычно указатель на структуру) в запросе.
Значение сохраняется в массиве `ctx` в позиции
`ctx_index` модуля.
Следующие макросы предоставляют удобный способ получения и установки контекстов запроса:
* `ngx_http_get_module_ctx(r, module)` — Возвращает
контекст `module`
* `ngx_http_set_ctx(r, c, module)` — Устанавливает `c`
как контекст `module`
* `main_conf`, `srv_conf`,
`loc_conf` — Массивы конфигураций текущего запроса.
Конфигурации сохраняются в позициях `ctx_index` модуля.
* `read_event_handler`, `write_event_handler` -
Обработчики событий чтения и записи для запроса.
Обычно как обработчики событий чтения, так и записи для HTTP-соединения
устанавливаются в `ngx_http_request_handler()`.
Эта функция вызывает обработчики `read_event_handler` и
`write_event_handler` для текущего активного запроса.
* `cache` — Объект кеша запроса для кеширования
ответа upstream.
* `upstream` — Объект upstream запроса для проксирования.
* `pool` — Пул запроса.
Сам объект запроса выделяется в этом пуле, который уничтожается при
удалении запроса.
Для выделений, которые должны быть доступны в течение всего времени жизни клиентского соединения,
используйте вместо этого пул `ngx_connection_t`.
* `header_in` — Буфер, в который читается заголовок
HTTP-запроса клиента.
* `headers_in`, `headers_out` — Объекты входящих и
исходящих HTTP-заголовков.
Оба объекта содержат поле `headers` типа
`ngx_list_t` для хранения сырого списка заголовков.
В дополнение к этому, специфические заголовки доступны для получения и установки как
отдельные поля, например `content_length_n`,
`status` и т.д.
* `request_body` — Объект тела запроса клиента.
* `start_sec`, `start_msec` — Момент времени, когда
запрос был создан, используется для отслеживания продолжительности запроса.
* `method`, `method_name` — Числовое и текстовое
представление метода HTTP-запроса клиента.
Числовые значения для методов определены в
`src/http/ngx_http_request.h` макросами
`NGX_HTTP_GET`, `NGX_HTTP_HEAD`,
`NGX_HTTP_POST` и т.д.
* `http_protocol` — Версия HTTP-протокола клиента в
оригинальной текстовой форме ("HTTP/1.0", "HTTP/1.1" и т.д.).
* `http_version` — Версия HTTP-протокола клиента в
числовой форме (`NGX_HTTP_VERSION_10`,
`NGX_HTTP_VERSION_11` и т.д.).
* `http_major`, `http_minor` — Версия HTTP-протокола
клиента в числовой форме, разделенная на основную и младшую части.
* `request_line`, `unparsed_uri` — Строка запроса
и URI в оригинальном запросе клиента.
* `uri`, `args`, `exten` —
URI, аргументы и расширение файла для текущего запроса.
Значение URI здесь может отличаться от оригинального URI, отправленного клиентом,
из-за нормализации.
В процессе обработки запроса эти значения могут изменяться при выполнении внутренних перенаправлений.
* `main` — Указатель на объект основного запроса.
Этот объект создается для обработки HTTP-запроса клиента, в отличие от
подзапросов, которые создаются для выполнения конкретной подзадачи в рамках основного запроса.
* `parent` — Указатель на родительский запрос подзапроса.
* `postponed` — Список выходных буферов и подзапросов в том
порядке, в котором они отправляются и создаются.
Список используется фильтром postpone для обеспечения согласованного вывода запроса,
когда части его создаются подзапросами.
* `post_subrequest` — Указатель на обработчик с контекстом,
который должен быть вызван при завершении подзапроса.
Не используется для основных запросов.
* `posted_requests` — Список запросов, которые должны быть запущены или
возобновлены, что выполняется путем вызова
`write_event_handler` запроса.
Обычно этот обработчик содержит основную функцию запроса, которая сначала выполняет
фазы запроса, а затем производит вывод.
Запрос обычно помещается в очередь вызовом
`ngx_http_post_request(r, NULL)`.
Он всегда помещается в список `posted_requests` основного запроса.
Функция `ngx_http_run_posted_requests(c)` выполняет все
запросы, которые помещены в очередь в основном запросе активного запроса
переданного соединения.
Все обработчики событий вызывают `ngx_http_run_posted_requests`,
что может привести к новым запросам в очереди.
Обычно она вызывается после вызова обработчика чтения или записи запроса.
* `phase_handler` — Индекс текущей фазы запроса.
* `phase_handler` — Индекс текущей фазы запроса.
* `ncaptures`, `captures`,
`captures_data` — Захваты регулярных выражений, полученные
при последнем совпадении регулярного выражения запроса.
Совпадение регулярного выражения может произойти в нескольких местах во время обработки запроса:
поиск в карте, поиск сервера по SNI или HTTP Host, перезапись, proxy_redirect и т.д.
Захваты, полученные при поиске, сохраняются в вышеупомянутых полях.
Поле `ncaptures` содержит количество захватов,
`captures` содержит границы захватов, а
`captures_data` содержит строку, с которой сравнивалось регулярное выражение
и которая используется для извлечения захватов.
После каждого нового совпадения регулярного выражения захваты запроса сбрасываются для хранения новых значений.
* `count` — Счетчик ссылок запроса.
Поле имеет смысл только для основного запроса.
Увеличение счетчика выполняется простым `r->main->count++`.
Для уменьшения счетчика вызовите
`ngx_http_finalize_request(r, rc)`.
Создание подзапроса и запуск процесса чтения тела запроса увеличивают счетчик.
* `subrequests` — Текущий уровень вложенности подзапросов.
Каждый подзапрос наследует уровень вложенности своего родителя, уменьшенный на единицу.
Если значение достигает нуля, генерируется ошибка.
Значение для основного запроса определяется константой
`NGX_HTTP_MAX_SUBREQUESTS`.
* `uri_changes` — Количество оставшихся изменений URI для
запроса.
Общее количество раз, когда запрос может изменить свой URI, ограничено константой
`NGX_HTTP_MAX_URI_CHANGES`.
С каждым изменением значение уменьшается до тех пор, пока не достигнет нуля, после чего
генерируется ошибка.
Перезаписи и внутренние перенаправления к обычным или именованным местоположениям считаются изменениями URI.
* `blocked` — Счетчик блокировок, удерживаемых на запросе.
Пока это значение не равно нулю, запрос не может быть завершен.
В настоящее время это значение увеличивается ожидающими операциями AIO (POSIX AIO и
операции потоков) и активной блокировкой кэша.
* `buffered` — Битовая маска, показывающая, какие модули буферизовали
вывод, произведенный запросом.
Ряд фильтров может буферизовать вывод; например, sub_filter может буферизовать данные
из-за частичного совпадения строки, copy filter может буферизовать данные из-за
отсутствия свободных буферов вывода и т.д.
Пока это значение не равно нулю, запрос не завершается
в ожидании сброса.
* `header_only` — Флаг, указывающий, что вывод не требует
тела.
Например, этот флаг используется HTTP-запросами HEAD.
* `keepalive` — Флаг, указывающий, поддерживается ли
keepalive клиентского соединения.
Значение выводится из версии HTTP и значения заголовка
"Connection".
* `header_sent` — Флаг, указывающий, что заголовок вывода
уже был отправлен запросом.
* `internal` — Флаг, указывающий, что текущий запрос
является внутренним.
Чтобы войти во внутреннее состояние, запрос должен пройти через внутреннее
перенаправление или быть подзапросом.
Внутренним запросам разрешено входить во внутренние местоположения.
* `allow_ranges` — Флаг, указывающий, что частичный ответ
может быть отправлен клиенту, как запрошено заголовком HTTP Range.
* `subrequest_ranges` — Флаг, указывающий, что частичный ответ
может быть отправлен во время обработки подзапроса.
* `single_range` — Флаг, указывающий, что только один непрерывный
диапазон выходных данных может быть отправлен клиенту.
Этот флаг обычно устанавливается при отправке потока данных, например, от
прокси-сервера, и весь ответ недоступен в одном буфере.
* `main_filter_need_in_memory`,
`filter_need_in_memory` — Флаги,
запрашивающие, чтобы вывод производился в буферах памяти, а не в файлах.
Это сигнал для copy filter читать данные из файловых буферов, даже если
sendfile включен.
Разница между двумя флагами заключается в расположении модулей фильтров, которые
их устанавливают.
Фильтры, вызываемые до фильтра postpone в цепочке фильтров, устанавливают
`filter_need_in_memory`, запрашивая, чтобы только вывод текущего
запроса поступал в буферы памяти.
Фильтры, вызываемые позже в цепочке фильтров, устанавливают
`main_filter_need_in_memory`, запрашивая, чтобы
как основной запрос, так и все подзапросы читали файлы в памяти
при отправке вывода.
* `filter_need_temporary` — Флаг, запрашивающий, чтобы вывод запроса
производился во временных буферах, но не в буферах памяти только для чтения или
файловых буферах.
Это используется фильтрами, которые могут изменять вывод непосредственно в буферах, где
он отправляется.
### Конфигурация
Каждый HTTP-модуль может иметь три типа конфигурации:
* Основная конфигурация — Применяется ко всему блоку `http`.
Функционирует как глобальные настройки для модуля.
* Конфигурация сервера — Применяется к одному блоку `server`.
Функционирует как специфичные для сервера настройки модуля.
* Конфигурация местоположения — Применяется к одному блоку `location`,
`if` или `limit_except`.
Функционирует как специфичные для местоположения настройки модуля.
Структуры конфигурации создаются на этапе конфигурации Angie путем
вызова функций, которые выделяют структуры, инициализируют их
и объединяют их.
Следующий пример показывает, как создать простую конфигурацию местоположения
для модуля.
Конфигурация имеет одну настройку, `foo`, типа
unsigned integer.
```c
typedef struct {
ngx_uint_t foo;
} ngx_http_foo_loc_conf_t;
static ngx_http_module_t ngx_http_foo_module_ctx = {
NULL, /* preconfiguration */
NULL, /* postconfiguration */
NULL, /* create main configuration */
NULL, /* init main configuration */
NULL, /* create server configuration */
NULL, /* merge server configuration */
ngx_http_foo_create_loc_conf, /* create location configuration */
ngx_http_foo_merge_loc_conf /* merge location configuration */
};
static void *
ngx_http_foo_create_loc_conf(ngx_conf_t *cf)
{
ngx_http_foo_loc_conf_t *conf;
conf = ngx_pcalloc(cf->pool, sizeof(ngx_http_foo_loc_conf_t));
if (conf == NULL) {
return NULL;
}
conf->foo = NGX_CONF_UNSET_UINT;
return conf;
}
static char *
ngx_http_foo_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)
{
ngx_http_foo_loc_conf_t *prev = parent;
ngx_http_foo_loc_conf_t *conf = child;
ngx_conf_merge_uint_value(conf->foo, prev->foo, 1);
}
```
Как видно из примера, функция `ngx_http_foo_create_loc_conf()`
создает новую структуру конфигурации, а
`ngx_http_foo_merge_loc_conf()` объединяет конфигурацию с
конфигурацией более высокого уровня.
На самом деле, конфигурации сервера и `location` существуют не только на уровнях
сервера и `location`, но также создаются для всех уровней выше них.
В частности, конфигурация сервера также создается на главном уровне, а
конфигурации `location` создаются на главном уровне, уровне сервера и уровне `location`.
Эти конфигурации позволяют указывать настройки, специфичные для сервера и `location`,
на любом уровне конфигурационного файла Angie.
В конечном итоге конфигурации объединяются вниз по иерархии.
Предоставляется ряд макросов, таких как `NGX_CONF_UNSET` и
`NGX_CONF_UNSET_UINT`, для обозначения отсутствующей настройки
и игнорирования ее при объединении.
Стандартные макросы объединения Angie, такие как `ngx_conf_merge_value()` и
`ngx_conf_merge_uint_value()`, предоставляют удобный способ
объединить настройку и установить значение по умолчанию, если ни одна из конфигураций
не предоставила явного значения.
Полный список макросов для различных типов см. в
`src/core/ngx_conf_file.h`.
Следующие макросы доступны
для доступа к конфигурации HTTP-модулей во время конфигурирования.
Все они принимают ссылку на `ngx_conf_t` в качестве первого аргумента.
* `ngx_http_conf_get_module_main_conf(cf, module)`
* `ngx_http_conf_get_module_srv_conf(cf, module)`
* `ngx_http_conf_get_module_loc_conf(cf, module)`
Следующий пример получает указатель на конфигурацию `location`
стандартного [основного модуля](https://angie.software//angie/docs/configuration/modules/http/index.md#http-core)
и заменяет обработчик содержимого `location`, хранящийся
в поле `handler` структуры.
```c
static ngx_int_t ngx_http_foo_handler(ngx_http_request_t *r);
static ngx_command_t ngx_http_foo_commands[] = {
{ ngx_string("foo"),
NGX_HTTP_LOC_CONF|NGX_CONF_NOARGS,
ngx_http_foo,
0,
0,
NULL },
ngx_null_command
};
static char *
ngx_http_foo(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
{
ngx_http_core_loc_conf_t *clcf;
clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);
clcf->handler = ngx_http_bar_handler;
return NGX_CONF_OK;
}
```
Следующие макросы доступны для доступа к конфигурации HTTP-модулей
во время выполнения.
* `ngx_http_get_module_main_conf(r, module)`
* `ngx_http_get_module_srv_conf(r, module)`
* `ngx_http_get_module_loc_conf(r, module)`
Эти макросы получают ссылку на HTTP-запрос
`ngx_http_request_t`.
Главная конфигурация запроса никогда не изменяется.
Конфигурация сервера может измениться с настроек по умолчанию после
выбора виртуального сервера для запроса.
Конфигурация `location`, выбранная для обработки запроса, может изменяться
несколько раз в результате операции перезаписи или внутреннего перенаправления.
Следующий пример показывает, как получить доступ к HTTP-конфигурации модуля
во время выполнения.
```c
static ngx_int_t
ngx_http_foo_handler(ngx_http_request_t *r)
{
ngx_http_foo_loc_conf_t *flcf;
flcf = ngx_http_get_module_loc_conf(r, ngx_http_foo_module);
...
}
```
### Фазы
Каждый HTTP-запрос проходит через последовательность фаз.
В каждой фазе выполняется определенный тип обработки запроса.
Специфичные для модуля обработчики могут быть зарегистрированы в большинстве фаз,
и многие стандартные модули Angie регистрируют свои обработчики фаз как способ
быть вызванными на определенной стадии обработки запроса.
Фазы обрабатываются последовательно, и обработчики фаз вызываются,
как только запрос достигает фазы.
Ниже приведен список фаз Angie HTTP.
* `NGX_HTTP_POST_READ_PHASE` — Первая фаза.
[RealIP](https://angie.software//angie/docs/configuration/modules/http/http_realip.md#http-realip)
регистрирует свой обработчик на этой фазе, чтобы включить
замену адресов клиентов до вызова любого другого модуля.
* `NGX_HTTP_SERVER_REWRITE_PHASE` — Фаза, где
обрабатываются директивы rewrite, определенные в блоке `server`
(но вне блока `location`).
[Rewrite](https://angie.software//angie/docs/configuration/modules/http/http_rewrite.md#http-rewrite)
устанавливает свой обработчик на этой фазе.
* `NGX_HTTP_FIND_CONFIG_PHASE` — Специальная фаза,
где выбирается `location` на основе URI запроса.
До этой фазы запросу назначается `location` по умолчанию для соответствующего виртуального сервера,
и любой модуль, запрашивающий конфигурацию `location`,
получает конфигурацию для `location` сервера по умолчанию.
Эта фаза назначает новый `location` запросу.
На этой фазе нельзя зарегистрировать дополнительные обработчики.
* `NGX_HTTP_REWRITE_PHASE` — То же самое, что и
`NGX_HTTP_SERVER_REWRITE_PHASE`, но для
правил rewrite, определенных в `location`, выбранном на предыдущей фазе.
* `NGX_HTTP_POST_REWRITE_PHASE` — Специальная фаза,
где запрос перенаправляется в новый `location`, если его URI изменился
во время rewrite.
Это реализуется путем прохождения запроса через
`NGX_HTTP_FIND_CONFIG_PHASE` снова.
На этой фазе нельзя зарегистрировать дополнительные обработчики.
* `NGX_HTTP_PREACCESS_PHASE` — Общая фаза для различных
типов обработчиков, не связанных с контролем доступа.
Стандартные модули Angie
[Limit Conn](https://angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#http-limit-conn) и
[Limit Req](https://angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req) регистрируют свои обработчики на этой фазе.
* `NGX_HTTP_ACCESS_PHASE` — Фаза, где проверяется,
что клиент авторизован для выполнения запроса.
Стандартные модули Angie, такие как
[Access](https://angie.software//angie/docs/configuration/modules/http/http_access.md#http-access) и
[Auth Basic](https://angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic) регистрируют свои обработчики на этой фазе.
По умолчанию клиент должен пройти проверку авторизации всех обработчиков,
зарегистрированных на этой фазе, чтобы запрос продолжился к следующей фазе.
Директива [satisfy](https://angie.software//angie/docs/configuration/modules/http/index.md#satisfy)
может использоваться для разрешения продолжения обработки, если любой из обработчиков фазы
авторизует клиента.
* `NGX_HTTP_POST_ACCESS_PHASE` — Специальная фаза, где обрабатывается
директива [satisfy](https://angie.software//angie/docs/configuration/modules/http/index.md#satisfy).
Если некоторые обработчики фазы доступа запретили доступ и ни один явно не разрешил его,
запрос завершается.
На этой фазе нельзя зарегистрировать дополнительные обработчики.
* `NGX_HTTP_PRECONTENT_PHASE` — Фаза для обработчиков, которые должны быть вызваны
до генерации контента.
Стандартные модули, такие как
[try_files](https://angie.software//angie/docs/configuration/modules/http/index.md#try-files) и
[Mirror](https://angie.software//angie/docs/configuration/modules/http/http_mirror.md#http-mirror),
регистрируют свои обработчики на этой фазе.
* `NGX_HTTP_CONTENT_PHASE` — Фаза, где обычно
генерируется ответ.
Множество стандартных модулей Angie регистрируют свои обработчики на этой фазе,
включая
[Index](https://angie.software//angie/docs/configuration/modules/http/http_index.md#http-index).
Они вызываются последовательно, пока один из них не произведет
вывод.
Также возможно установить обработчики контента для каждого `location` отдельно.
Если в конфигурации `location`
[HTTP-модуль](https://angie.software//angie/docs/configuration/modules/http/index.md#http-core) установлен `handler`, он
установлен `handler`, он
вызывается как обработчик контента, и обработчики, установленные на этой фазе,
игнорируются.
* `NGX_HTTP_LOG_PHASE` — Фаза, где выполняется
логирование запроса.
В настоящее время только
[Log](https://angie.software//angie/docs/configuration/modules/http/http_log.md#http-log)
регистрирует свой обработчик
на этой стадии для логирования доступа.
Обработчики фазы логирования вызываются в самом конце обработки запроса, прямо
перед освобождением запроса.
Ниже приведен пример обработчика фазы preaccess.
```c
static ngx_http_module_t ngx_http_foo_module_ctx = {
NULL, /* preconfiguration */
ngx_http_foo_init, /* postconfiguration */
NULL, /* create main configuration */
NULL, /* init main configuration */
NULL, /* create server configuration */
NULL, /* merge server configuration */
NULL, /* create location configuration */
NULL /* merge location configuration */
};
static ngx_int_t
ngx_http_foo_handler(ngx_http_request_t *r)
{
ngx_table_elt_t *ua;
ua = r->headers_in.user_agent;
if (ua == NULL) {
return NGX_DECLINED;
}
/* reject requests with "User-Agent: foo" */
if (ua->value.len == 3 && ngx_strncmp(ua->value.data, "foo", 3) == 0) {
return NGX_HTTP_FORBIDDEN;
}
return NGX_DECLINED;
}
static ngx_int_t
ngx_http_foo_init(ngx_conf_t *cf)
{
ngx_http_handler_pt *h;
ngx_http_core_main_conf_t *cmcf;
cmcf = ngx_http_conf_get_module_main_conf(cf, ngx_http_core_module);
h = ngx_array_push(&cmcf->phases[NGX_HTTP_PREACCESS_PHASE].handlers);
if (h == NULL) {
return NGX_ERROR;
}
*h = ngx_http_foo_handler;
return NGX_OK;
}
```
Ожидается, что обработчики фаз возвращают определенные коды:
* `NGX_OK` — перейти к следующей фазе.
* `NGX_DECLINED` — перейти к следующему обработчику текущей
фазы.
Если текущий обработчик является последним в текущей фазе,
перейти к следующей фазе.
* `NGX_AGAIN`, `NGX_DONE` — приостановить
обработку фазы до некоторого будущего события, которым может быть
асинхронная операция ввода-вывода или просто задержка, например.
Предполагается, что обработка фазы будет возобновлена позже путем вызова
`ngx_http_core_run_phases()`.
* Любое другое значение, возвращаемое обработчиком фазы, рассматривается как код
завершения запроса, в частности, как код HTTP-ответа.
Запрос завершается с предоставленным кодом.
Для некоторых фаз коды возврата обрабатываются несколько по-другому.
На фазе содержимого любой код возврата, отличный от
`NGX_DECLINED`, считается кодом завершения.
Любой код возврата от обработчиков содержимого местоположения считается
кодом завершения.
На фазе доступа в режиме
[satisfy any](https://angie.software//angie/docs/configuration/modules/http/index.md#satisfy)
любой код возврата, отличный от `NGX_OK`,
`NGX_DECLINED`, `NGX_AGAIN`,
`NGX_DONE`, считается отказом.
Если никакие последующие обработчики доступа не разрешают или не запрещают доступ с другим
кодом, код отказа станет кодом завершения.
### Примеры
Репозиторий
[nginx-dev-examples](https://github.com/nginx/nginx-dev-examples)
предоставляет примеры модулей nginx, подходящие и для Angie.
## Стиль кода
### Общие правила
* максимальная ширина текста составляет 80 символов
* отступ составляет 4 пробела
* никаких табуляций, никаких завершающих пробелов
* элементы списка на одной строке разделяются пробелами
* шестнадцатеричные литералы записываются строчными буквами
* имена файлов, функций и типов, а также глобальные переменные имеют
префикс `ngx_` или более специфичный префикс, такой как
`ngx_http_` и `ngx_mail_`
```c
size_t
ngx_utf8_length(u_char *p, size_t n)
{
u_char c, *last;
size_t len;
last = p + n;
for (len = 0; p < last; len++) {
c = *p;
if (c < 0x80) {
p++;
continue;
}
if (ngx_utf8_decode(&p, last - p) > 0x10ffff) {
/* invalid UTF-8 */
return n;
}
}
return len;
}
```
### Файлы
Типичный исходный файл может содержать следующие разделы, разделенные
двумя пустыми строками:
* заявления об авторских правах
* включения
* определения препроцессора
* определения типов
* прототипы функций
* определения переменных
* определения функций
Заявления об авторских правах выглядят следующим образом:
```c
/*
* Copyright (C) Author Name
* Copyright (C) Organization, Inc.
*/
```
Если файл значительно изменяется, список авторов должен быть обновлен,
новый автор добавляется в начало.
Файлы `ngx_config.h` и `ngx_core.h`
всегда включаются первыми, за ними следует один из
`ngx_http.h`, `ngx_stream.h`,
или `ngx_mail.h`.
Затем следуют необязательные внешние заголовочные файлы:
```c
#include
#include
#include
#include
#include
#include
#if (NGX_HAVE_EXSLT)
#include
#endif
```
Заголовочные файлы должны включать так называемую "защиту заголовка":
```c
#ifndef _NGX_PROCESS_CYCLE_H_INCLUDED_
#define _NGX_PROCESS_CYCLE_H_INCLUDED_
...
#endif /* _NGX_PROCESS_CYCLE_H_INCLUDED_ */
```
### Комментарии
* комментарии `//` не используются
* текст написан на английском языке, предпочтительна американская орфография
* многострочные комментарии форматируются следующим образом:
```c
/*
* The red-black tree code is based on the algorithm described in
* the "Introduction to Algorithms" by Cormen, Leiserson and Rivest.
*/
```
```c
/* find the server configuration for the address:port */
```
### Препроцессор
Имена макросов начинаются с префикса `ngx_` или `NGX_`
(или более специфичного).
Имена макросов для констант записываются прописными буквами.
Параметризованные макросы и макросы для инициализаторов записываются строчными буквами.
Имя макроса и значение разделяются как минимум двумя пробелами:
```c
#define NGX_CONF_BUFFER 4096
#define ngx_buf_in_memory(b) (b->temporary || b->memory || b->mmap)
#define ngx_buf_size(b) \
(ngx_buf_in_memory(b) ? (off_t) (b->last - b->pos): \
(b->file_last - b->file_pos))
#define ngx_null_string { 0, NULL }
```
Условия заключаются в скобки, отрицание находится снаружи:
```c
#if (NGX_HAVE_KQUEUE)
...
#elif ((NGX_HAVE_DEVPOLL && !(NGX_TEST_BUILD_DEVPOLL)) \
|| (NGX_HAVE_EVENTPORT && !(NGX_TEST_BUILD_EVENTPORT)))
...
#elif (NGX_HAVE_EPOLL && !(NGX_TEST_BUILD_EPOLL))
...
#elif (NGX_HAVE_POLL)
...
#else /* select */
...
#endif /* NGX_HAVE_KQUEUE */
```
### Типы
Имена типов заканчиваются суффиксом `_t`.
Определенное имя типа отделяется как минимум двумя пробелами:
```c
typedef ngx_uint_t ngx_rbtree_key_t;
```
Типы структур определяются с использованием `typedef`.
Внутри структур типы и имена членов выравниваются:
```c
typedef struct {
size_t len;
u_char *data;
} ngx_str_t;
```
Сохраняйте одинаковое выравнивание среди различных структур в файле.
Структура, которая указывает на себя, имеет имя, заканчивающееся на
`_s`.
Соседние определения структур разделяются двумя пустыми строками:
```c
typedef struct ngx_list_part_s ngx_list_part_t;
struct ngx_list_part_s {
void *elts;
ngx_uint_t nelts;
ngx_list_part_t *next;
};
typedef struct {
ngx_list_part_t *last;
ngx_list_part_t part;
size_t size;
ngx_uint_t nalloc;
ngx_pool_t *pool;
} ngx_list_t;
```
Каждый член структуры объявляется на отдельной строке:
```c
typedef struct {
ngx_uint_t hash;
ngx_str_t key;
ngx_str_t value;
u_char *lowcase_key;
} ngx_table_elt_t;
```
Указатели на функции внутри структур имеют определенные типы, заканчивающиеся
на `_pt`:
```c
typedef ssize_t (*ngx_recv_pt)(ngx_connection_t *c, u_char *buf, size_t size);
typedef ssize_t (*ngx_recv_chain_pt)(ngx_connection_t *c, ngx_chain_t *in,
off_t limit);
typedef ssize_t (*ngx_send_pt)(ngx_connection_t *c, u_char *buf, size_t size);
typedef ngx_chain_t *(*ngx_send_chain_pt)(ngx_connection_t *c, ngx_chain_t *in,
off_t limit);
typedef struct {
ngx_recv_pt recv;
ngx_recv_chain_pt recv_chain;
ngx_recv_pt udp_recv;
ngx_send_pt send;
ngx_send_pt udp_send;
ngx_send_chain_pt udp_send_chain;
ngx_send_chain_pt send_chain;
ngx_uint_t flags;
} ngx_os_io_t;
```
Перечисления имеют типы, заканчивающиеся на `_e`:
```c
typedef enum {
ngx_http_fastcgi_st_version = 0,
ngx_http_fastcgi_st_type,
...
ngx_http_fastcgi_st_padding
} ngx_http_fastcgi_state_e;
```
### Переменные
Переменные объявляются отсортированными по длине базового типа, затем в алфавитном порядке.
Имена типов и имена переменных выравниваются.
"Столбцы" типа и имени разделяются двумя пробелами.
Большие массивы помещаются в конец блока объявлений:
```c
u_char *rv, *p;
ngx_conf_t *cf;
ngx_uint_t i, j, k;
unsigned int len;
struct sockaddr *sa;
const unsigned char *data;
ngx_peer_connection_t *pc;
ngx_http_core_srv_conf_t **cscfp;
ngx_http_upstream_srv_conf_t *us, *uscf;
u_char text[NGX_SOCKADDR_STRLEN];
```
Статические и глобальные переменные могут быть инициализированы при объявлении:
```c
static ngx_str_t ngx_http_memcached_key = ngx_string("memcached_key");
```
```c
static ngx_uint_t mday[] = { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 };
```
```c
static uint32_t ngx_crc32_table16[] = {
0x00000000, 0x1db71064, 0x3b6e20c8, 0x26d930ac,
...
0x9b64c2b0, 0x86d3d2d4, 0xa00ae278, 0xbdbdf21c
};
```
Существует множество часто используемых комбинаций тип/имя:
```c
u_char *rv;
ngx_int_t rc;
ngx_conf_t *cf;
ngx_connection_t *c;
ngx_http_request_t *r;
ngx_peer_connection_t *pc;
ngx_http_upstream_srv_conf_t *us, *uscf;
```
### Функции
Все функции (даже статические) должны иметь прототипы.
Прототипы включают имена аргументов.
Длинные прототипы переносятся с одним отступом на строках продолжения:
```c
static char *ngx_http_block(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
static ngx_int_t ngx_http_init_phases(ngx_conf_t *cf,
ngx_http_core_main_conf_t *cmcf);
static char *ngx_http_merge_servers(ngx_conf_t *cf,
ngx_http_core_main_conf_t *cmcf, ngx_http_module_t *module,
ngx_uint_t ctx_index);
```
Имя функции в определении начинается с новой строки.
Открывающая и закрывающая скобки тела функции находятся на отдельных строках.
Тело функции имеет отступ.
Между функциями есть две пустые строки:
```c
static ngx_int_t
ngx_http_find_virtual_server(ngx_http_request_t *r, u_char *host, size_t len)
{
...
}
static ngx_int_t
ngx_http_add_addresses(ngx_conf_t *cf, ngx_http_core_srv_conf_t *cscf,
ngx_http_conf_port_t *port, ngx_http_listen_opt_t *lsopt)
{
...
}
```
Нет пробела после имени функции и открывающей скобки.
Длинные вызовы функций переносятся таким образом, что строки продолжения начинаются
с позиции первого аргумента функции.
Если это невозможно, отформатируйте первую строку продолжения так, чтобы она
заканчивалась на позиции 79:
```c
ngx_log_debug2(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
"http header: \"%V: %V\"",
&h->key, &h->value);
hc->busy = ngx_palloc(r->connection->pool,
cscf->large_client_header_buffers.num * sizeof(ngx_buf_t *));
```
Макрос `ngx_inline` следует использовать вместо
`inline`:
```c
static ngx_inline void ngx_cpuid(uint32_t i, uint32_t *buf);
```
### Выражения
Бинарные операторы, кроме `.` и `->`,
должны быть отделены от своих операндов одним пробелом.
Унарные операторы и индексы не отделяются от своих операндов пробелами:
```c
width = width * 10 + (*fmt++ - '0');
```
```c
ch = (u_char) ((decoded << 4) + (ch - '0'));
```
```c
r->exten.data = &r->uri.data[i + 1];
```
Приведения типов отделяются одним пробелом от приводимых выражений.
Звездочка внутри приведения типа отделяется пробелом от имени типа:
```c
len = ngx_sock_ntop((struct sockaddr *) sin6, p, len, 1);
```
Если выражение не помещается в одну строку, оно переносится.
Предпочтительное место для разрыва строки — бинарный оператор.
Строка продолжения выравнивается с началом выражения:
```c
if (status == NGX_HTTP_MOVED_PERMANENTLY
|| status == NGX_HTTP_MOVED_TEMPORARILY
|| status == NGX_HTTP_SEE_OTHER
|| status == NGX_HTTP_TEMPORARY_REDIRECT
|| status == NGX_HTTP_PERMANENT_REDIRECT)
{
...
}
```
```c
p->temp_file->warn = "an upstream response is buffered "
"to a temporary file";
```
В крайнем случае можно перенести выражение так, чтобы
строка продолжения заканчивалась на позиции 79:
```c
hinit->hash = ngx_pcalloc(hinit->pool, sizeof(ngx_hash_wildcard_t)
+ size * sizeof(ngx_hash_elt_t *));
```
Вышеуказанные правила также применяются к подвыражениям,
где каждое подвыражение имеет свой собственный уровень отступа:
```c
if (((u->conf->cache_use_stale & NGX_HTTP_UPSTREAM_FT_UPDATING)
|| c->stale_updating) && !r->background
&& u->conf->cache_background_update)
{
...
}
```
Иногда удобно перенести выражение после приведения типа.
В этом случае строка продолжения имеет отступ:
```c
node = (ngx_rbtree_node_t *)
((u_char *) lr - offsetof(ngx_rbtree_node_t, color));
```
Указатели явно сравниваются с
`NULL` (не с `0`):
```c
if (ptr != NULL) {
...
}
```
### Условные операторы и циклы
Ключевое слово `if` отделяется от условия
одним пробелом.
Открывающая скобка располагается на той же строке или на
отдельной строке, если условие занимает несколько строк.
Закрывающая скобка располагается на отдельной строке, опционально за которой следует
`else if` / `else`.
Обычно перед частью
`else if` / `else` есть пустая строка:
```c
if (node->left == sentinel) {
temp = node->right;
subst = node;
} else if (node->right == sentinel) {
temp = node->left;
subst = node;
} else {
subst = ngx_rbtree_min(node->right, sentinel);
if (subst->left != sentinel) {
temp = subst->left;
} else {
temp = subst->right;
}
}
```
Аналогичные правила форматирования применяются к циклам `do`
и `while`:
```c
while (p < last && *p == ' ') {
p++;
}
```
```c
do {
ctx->node = rn;
ctx = ctx->next;
} while (ctx);
```
Ключевое слово `switch` отделяется от условия
одним пробелом.
Открывающая скобка располагается на той же строке.
Закрывающая скобка располагается на отдельной строке.
Ключевые слова `case` выравниваются с
`switch`:
```c
switch (ch) {
case '!':
looked = 2;
state = ssi_comment0_state;
break;
case '<':
copy_end = p;
break;
default:
copy_end = p;
looked = 0;
state = ssi_start_state;
break;
}
```
Большинство циклов `for` форматируются следующим образом:
```c
for (i = 0; i < ccf->env.nelts; i++) {
...
}
```
```c
for (q = ngx_queue_head(locations);
q != ngx_queue_sentinel(locations);
q = ngx_queue_next(q))
{
...
}
```
Если какая-то часть оператора `for` опущена,
это обозначается комментарием `/* void */`:
```c
for (i = 0; /* void */ ; i++) {
...
}
```
Цикл с пустым телом также обозначается комментарием
`/* void */`, который может быть размещен на той же строке:
```c
for (cl = *busy; cl->next; cl = cl->next) { /* void */ }
```
Бесконечный цикл выглядит следующим образом:
```c
for ( ;; ) {
...
}
```
### Метки
Метки окружаются пустыми строками и имеют отступ на предыдущем уровне:
```c
if (i == 0) {
u->err = "host not found";
goto failed;
}
u->addrs = ngx_pcalloc(pool, i * sizeof(ngx_addr_t));
if (u->addrs == NULL) {
goto failed;
}
u->naddrs = i;
...
return NGX_OK;
failed:
freeaddrinfo(res);
return NGX_ERROR;
```
## Отладка проблем с памятью
Для отладки проблем с памятью, таких как переполнение буферов или использование освобожденной памяти, вы
можете использовать [AddressSanitizer](https://en.wikipedia.org/wiki/AddressSanitizer)
(ASan), поддерживаемый некоторыми современными компиляторами.
Для включения ASan с `gcc` и `clang`
используйте опцию компилятора и компоновщика `-fsanitize=address`.
При сборке Angie это можно сделать, добавив опцию к
параметрам `--with-cc-opt` и `--with-ld-opt`
скрипта `configure`.
Поскольку большинство выделений памяти в Angie производится из внутреннего
[пула](#pool) Angie, включение ASan не всегда может быть достаточным для отладки
проблем с памятью.
Внутренний пул выделяет большой блок памяти из системы и вырезает
из него меньшие выделения.
Однако этот механизм можно отключить, установив
макрос `NGX_DEBUG_PALLOC` в `1`.
В этом случае выделения передаются напрямую системному аллокатору, предоставляя ему
полный контроль над границами буферов.
Следующая строка конфигурации обобщает информацию, представленную выше.
Она рекомендуется при разработке сторонних модулей и тестировании Angie на
различных платформах.
```bash
auto/configure --with-cc-opt='-fsanitize=address -DNGX_DEBUG_PALLOC=1'
--with-ld-opt=-fsanitize=address
```
## Распространенные ошибки
### Написание C-модуля
Наиболее распространенная ошибка — это попытка написать полноценный C-модуль,
когда этого можно избежать.
В большинстве случаев ваша задача может быть решена созданием правильной конфигурации.
Если написание модуля неизбежно, постарайтесь сделать его
максимально маленьким и простым.
Например, модуль может только экспортировать некоторые
`переменные <#http_variables>`.
Перед началом создания модуля рассмотрите следующие вопросы:
* Возможно ли реализовать желаемую функциональность, используя уже
[Собственные модули](https://angie.software//angie/docs/configuration/modules/index.md#modules)?
* Возможно ли решить проблему, используя встроенные языки сценариев,
такие как [perl](https://angie.software//angie/docs/configuration/modules/http/http_perl.md#id4) или [NJS](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs)?
### C-строки
Наиболее используемый тип строк в Angie,
`ngx_str_t <#string_overview>`, не является C-строкой,
завершающейся нулем.
Вы не можете передавать данные в стандартные функции библиотеки C,
такие как `strlen()` или `strstr()`.
Вместо этого следует использовать Angie `аналоги <#string_overview>`,
которые принимают либо `ngx_str_t`, либо указатель на данные и длину.
Однако есть случай, когда `ngx_str_t` содержит
указатель на строку, завершающуюся нулем: строки, которые получаются в результате
разбора файла конфигурации, завершаются нулем.
### Глобальные переменные
Избегайте использования глобальных переменных в ваших модулях.
Скорее всего, наличие глобальной переменной является ошибкой.
Любые глобальные данные должны быть привязаны к `циклу конфигурации <#cycle>`
и выделяться из соответствующего `пула памяти <#pool>`.
Это позволяет Angie выполнять плавную перезагрузку конфигурации.
Попытка использовать глобальные переменные, вероятно, нарушит эту функциональность,
поскольку будет невозможно иметь две конфигурации одновременно
и избавляться от них.
Иногда глобальные переменные необходимы.
В этом случае требуется особое внимание для правильного управления
реконфигурацией.
Также проверьте, имеют ли библиотеки, используемые вашим кодом, неявное
глобальное состояние, которое может быть нарушено при перезагрузке.
### Ручное управление памятью
Вместо работы с подходом malloc/free, который подвержен ошибкам,
изучите, как использовать Angie `пулы <#pool>`.
Пул создается и привязывается к объекту —
`конфигурации <#http_conf>`,
`циклу <#cycle>`,
`соединению <#connection>`
или `HTTP-запросу <#http_request>`.
Когда объект уничтожается, связанный пул также уничтожается.
Поэтому при работе с объектом можно выделить необходимое количество памяти
из соответствующего пула и не заботиться об освобождении памяти
даже в случае ошибок.
### Потоки
Рекомендуется избегать использования потоков в Angie, поскольку это
определенно нарушит работу: большинство функций Angie не являются потокобезопасными.
Ожидается, что поток будет выполнять только системные вызовы и
потокобезопасные функции библиотек.
Если вам нужно выполнить код, не связанный с обработкой клиентских запросов,
правильный способ — запланировать таймер в обработчике модуля `init_process`
и выполнить необходимые действия в обработчике таймера.
Внутренне Angie использует `потоки <#threads>` для
ускорения операций, связанных с вводом-выводом, но это особый случай с множеством
ограничений.
### Блокирующие библиотеки
Распространенная ошибка — использование библиотек, которые внутренне блокируют выполнение.
Большинство существующих библиотек являются синхронными и блокирующими по своей природе.
Другими словами, они выполняют одну операцию за раз и тратят
время на ожидание ответа от другой стороны.
В результате, когда запрос обрабатывается с помощью такой библиотеки, весь
рабочий процесс Angie блокируется, что разрушает производительность.
Используйте только библиотеки, которые предоставляют асинхронный интерфейс и не
блокируют весь процесс.
### HTTP-запросы к внешним сервисам
Часто модулям необходимо выполнить HTTP-вызов к какому-либо внешнему сервису.
Распространенная ошибка — использование какой-либо внешней библиотеки, такой как libcurl,
для выполнения HTTP-запроса.
Совершенно не нужно привносить огромное количество внешнего
(вероятно, `блокирующего <#using_libraries>`!) кода
для задачи, которая может быть выполнена самим Angie.
Существует два основных сценария использования, когда необходим внешний запрос:
* в контексте обработки клиентского запроса (например, в обработчике содержимого)
* в контексте рабочего процесса (например, обработчик таймера)
В первом случае лучше всего использовать
`API подзапросов <#http_subrequests>`.
Вместо прямого обращения к внешнему сервису вы объявляете `location`
в конфигурации Angie и направляете свой подзапрос к этому `location`.
Этот `location` не ограничивается
[проксированием](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass)
запросов, но может содержать другие директивы Angie.
Пример такого подхода — директива
[auth_request](https://angie.software//angie/docs/configuration/modules/http/http_auth_request.md#id3),
реализованная в модуле
auth_request.
Для второго случая можно использовать базовую функциональность HTTP-клиента,
доступную в Angie.
Например,
[модуль OCSP](https://github.com/nginx/nginx/blob/master/src/event/ngx_event_openssl_stapling.c)
реализует простой HTTP-клиент.
# https://angie.software/angie/docs/oss_changes.md
# История версий Angie
## 2026
### Angie 1.11.8
Дата выпуска: 18.06.2026.
#### Безопасность
- При проксировании специально созданного запроса к gRPC-серверу с директивой
[ignore_invalid_headers](https://angie.software//angie/docs/configuration/modules/http/index.md#ignore-invalid-headers), установленной в `off`, и директивой
[large_client_header_buffers](https://angie.software//angie/docs/configuration/modules/http/index.md#large-client-header-buffers) с большим значением могло произойти
переполнение буфера, что позволяло атакующему испортить память рабочего
процесса или вызвать его падение
([CVE-2026-42055](https://nvd.nist.gov/vuln/detail/CVE-2026-42055));
исправление портировано из nginx 1.31.2.
- При обработке специально созданного ответа с декодированием из UTF-8 через
директиву [charset_map](https://angie.software//angie/docs/configuration/modules/http/http_charset.md#charset-map) могло происходить чтение данных за границами
буфера рабочего процесса, что позволяло атакующему отправить клиенту
ограниченное содержимое памяти рабочего процесса или вызвать его падение
([CVE-2026-48142](https://nvd.nist.gov/vuln/detail/CVE-2026-48142));
исправление портировано из nginx 1.31.2.
#### Исправления
- IP-адрес без номера порта в директивах [acme_http_port](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-http-port) или
[acme_dns_port](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-dns-port) вызывал падение главного процесса при чтении
конфигурации.
#### Пакеты
- Обновлены:
- [angie-module-keyval](https://angie.software//angie/docs/installation/external-modules/keyval.md#external-keyval) — до версии 0.5.0
### Angie 1.11.7
Дата выпуска: 15.06.2026.
#### Добавления
- Совместимость с OpenSSL 4.0.
#### Исправления
- В некоторых конфигурациях ответ на ACME DNS-проверку мог отправляться не
с того IP-адреса/интерфейса, на который был отправлен запрос, что могло
приводить к ошибке выпуска сертификата.
- При использовании [Docker-модуля](https://angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) быстрое завершение
контейнеров сразу после старта могло вызывать падение рабочего процесса.
- Изменение параметров в директивах [metric_zone](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-zone) или
[metric_complex_zone](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-complex-zone) для уже существующей зоны
могло привести к падению рабочего процесса при перезагрузке конфигурации.
- При использовании параметра `window=` метрики типа
`average mean` результат на некоторых периодах мог вычисляться
неправильно; в частности, вскоре после запуска системы на Linux значения
могли оставаться нулевыми.
- Значения метрик типов `count` и `histogram` неправильно
выводились на 32-битных платформах после достижения 2^32-1.
- Сборка завершалась ошибкой при использовании опции `./configure`
`--with-stream=dynamic` в сочетании с
`--with-stream_acme_module`; проблема появилась в 1.10.3.
#### Пакеты
- Обновлены:
- [angie-module-auth-jwt](https://angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) — до версии 0.14.1
- [angie-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии v0.47.0
- [angie-module-vod](https://angie.software//angie/docs/installation/external-modules/vod.md#external-vod) — до версии v1.8.1
### Angie 1.11.6
Дата выпуска: 25.05.2026.
#### Безопасность
- При использовании директивы [rewrite](https://angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) с регулярным
выражением, содержащим вложенные захваты PCRE, и строкой замены,
ссылающейся на несколько таких захватов, атакующий при некоторых
независящих от него обстоятельствах мог вызвать падение рабочего
процесса, а на системах без рандомизации адресного пространства —
выполнение произвольного кода
([CVE-2026-9256](https://nvd.nist.gov/vuln/detail/CVE-2026-9256));
исправление портировано из nginx 1.31.1.
#### Пакеты
- Обновлены:
- [angie-module-auth-jwt](https://angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) — до версии 0.13.1
- [angie-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.9.9
- [angie-module-testcookie](https://angie.software//angie/docs/installation/external-modules/testcookie.md#external-testcookie) — до версии 7d263d4
- [angie-module-vod](https://angie.software//angie/docs/installation/external-modules/vod.md#external-vod) — до версии v1.7.2
### Angie 1.11.5
Дата выпуска: 15.05.2026.
#### Безопасность
- При использовании директивы [rewrite](https://angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) с неименованным
захватом (например, `$1`, `$2`) и строкой замены, содержащей символ `?`,
за которой следует директива [rewrite](https://angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5), [if](https://angie.software//angie/docs/configuration/modules/http/http_rewrite.md#if) или [set](https://angie.software//angie/docs/configuration/modules/http/http_rewrite.md#set), атакующий при
некоторых независящих от него обстоятельствах мог вызвать падение
рабочего процесса, а на системах без рандомизации адресного
пространства — выполнение произвольного кода
([CVE-2026-42945](https://nvd.nist.gov/vuln/detail/CVE-2026-42945));
исправление портировано из nginx 1.31.0.
- При использовании директивы [ssl_ocsp](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ocsp) во время
обработки ответов DNS-сервера могло произойти обращение к ранее
освобождённой памяти, что позволяло атакующему повредить память
рабочего процесса или вызвать его падение
([CVE-2026-40701](https://nvd.nist.gov/vuln/detail/CVE-2026-40701));
исправление портировано из nginx 1.31.0.
- При использовании HTTP/3 атакующий мог выполнить
подмену IP-адреса и тем самым обойти ограничения или авторизацию в
некоторых конфигурациях
([CVE-2026-40460](https://nvd.nist.gov/vuln/detail/CVE-2026-40460));
исправление портировано из nginx 1.31.0.
- При использовании директив [scgi_pass](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass) или [uwsgi_pass](https://angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass)
атакующий, находясь в позиции посредника (MITM) и контролируя ответы
проксируемого сервера, мог вызвать избыточное выделение памяти или
чтение за пределами буфера, что позволяло отправить клиенту
содержимое памяти рабочего процесса или вызвать его падение
([CVE-2026-42946](https://nvd.nist.gov/vuln/detail/CVE-2026-42946));
исправление портировано из nginx 1.31.0.
- При обработке специально созданного ответа с
декодированием из UTF-8 через директиву [charset_map](https://angie.software//angie/docs/configuration/modules/http/http_charset.md#charset-map) могло
происходить чтение данных за границами буфера рабочего процесса, что
позволяло атакующему при некоторых независящих от него
обстоятельствах отправить клиенту ограниченное содержимое памяти
рабочего процесса или вызвать его падение
([CVE-2026-42934](https://nvd.nist.gov/vuln/detail/CVE-2026-42934));
исправление портировано из nginx 1.31.0.
#### Пакеты
- Обновлены:
- [angie-module-auth-totp](https://angie.software//angie/docs/installation/external-modules/auth-totp.md#external-auth-totp) — до версии 1.2.0
- [angie-module-cache-purge](https://angie.software//angie/docs/installation/external-modules/cache-purge.md#external-cache-purge) — до версии 3.0.2
- [angie-module-keyval](https://angie.software//angie/docs/installation/external-modules/keyval.md#external-keyval) — до версии 0.4.0
- [angie-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.9.8
- [angie-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии v0.46.0
- Изменён источник [angie-module-dav-ext](https://angie.software//angie/docs/installation/external-modules/dav-ext.md#external-dav-ext) на
[mid1221213/nginx-dav-ext-module](https://github.com/mid1221213/nginx-dav-ext-module) v4.0.1.
- Изменён источник [angie-module-vod](https://angie.software//angie/docs/installation/external-modules/vod.md#external-vod) на
[dio-az/nginx-vod-module](https://github.com/dio-az/nginx-vod-module) v1.7.1.
### Angie 1.11.4
Дата выпуска: 25.03.2026.
#### Безопасность
- TLS-согласование с клиентом в [stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream)-модуле могло
завершиться успешно при том, что OCSP отклонил клиентский сертификат
([CVE-2026-28755](https://nvd.nist.gov/vuln/detail/CVE-2026-28755));
исправление портировано из nginx 1.29.7.
- В DAV-модуле при обработке COPY- или MOVE-запроса в
`location` с директивой [alias](https://angie.software//angie/docs/configuration/modules/http/index.md#alias) могло произойти переполнение буфера,
что позволяло атакующему модифицировать исходный или целевой путь за
пределы корневой директории
([CVE-2026-27654](https://nvd.nist.gov/vuln/detail/CVE-2026-27654));
исправление портировано из nginx 1.29.7.
- Обработка специально созданного файла в MP4-модуле на
32-битных платформах могла приводить к падению рабочего процесса, а
также потенциально могла иметь другие последствия
([CVE-2026-27784](https://nvd.nist.gov/vuln/detail/CVE-2026-27784));
исправление портировано из nginx 1.29.7.
- Обработка специально созданного файла MP4-модулем могла
приводить к падению рабочего процесса, а также потенциально могла
иметь другие последствия
([CVE-2026-32647](https://nvd.nist.gov/vuln/detail/CVE-2026-32647));
исправление портировано из nginx 1.29.7.
- Если в почтовом прокси-модуле ([Mail](https://angie.software//angie/docs/configuration/modules/index.md#modules-mail)) использовался метод
аутентификации CRAM-MD5 или APOP и были разрешены повторные попытки
аутентификации, то могло произойти падение рабочего процесса
([CVE-2026-27651](https://nvd.nist.gov/vuln/detail/CVE-2026-27651));
исправление портировано из nginx 1.29.7.
- Когда использовался почтовый прокси-модуль ([Mail](https://angie.software//angie/docs/configuration/modules/index.md#modules-mail)), атакующий с
помощью PTR DNS-записи мог вставить данные в HTTP-запросы
аутентификации, а также в команду XCLIENT в SMTP-соединении к
проксируемому серверу
([CVE-2026-28753](https://nvd.nist.gov/vuln/detail/CVE-2026-28753));
исправление портировано из nginx 1.29.7.
#### Исправления
- Редкие системные ошибки перед подключением к
проксируемому серверу могли повлиять на корректность статуса
проксируемых серверов в модулях [HTTP](https://angie.software//angie/docs/configuration/modules/index.md#modules-http) и
[stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream); в [stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream)-модуле они
также могли привести к падению рабочего процесса; проблема появилась
в 1.9.1.
- В конфигурациях, где директивы [proxy_http_version](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version) `3` и
[proxy_set_header](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-set-header) `Host ..` наследовались из блока `http`,
исходящие HTTP/3-запросы могли отправляться без заголовка `Host`.
#### Пакеты
- Обновлены:
- [angie-module-auth-jwt](https://angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) — до версии 0.11.0
- [angie-module-cache-purge](https://angie.software//angie/docs/installation/external-modules/cache-purge.md#external-cache-purge) — до версии 2.5.6
- [angie-module-cgi](https://angie.software//angie/docs/installation/external-modules/cgi.md#external-cgi) — до версии v0.15
- [angie-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.9.6
- [angie-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии v0.43.0
### Angie 1.11.3
Дата выпуска: 06.02.2026.
#### Безопасность
- Атакующий, находясь в позиции посредника (MITM) перед проксируемым сервером
с использованием TLS, при некоторых независящих от него обстоятельствах мог
внедрить в ответ данные в виде открытого текста до начала TLS-согласования
([CVE-2026-1642](https://nvd.nist.gov/vuln/detail/CVE-2026-1642));
исправление портировано из nginx 1.29.5.
#### Пакеты
- Обновлены:
- [angie-module-jwt](https://angie.software//angie/docs/installation/external-modules/jwt.md#external-jwt) — до версии 3.4.4
### Angie 1.11.2
Дата выпуска: 15.01.2026.
#### Исправления
- Если BPF был отключен, то HTTP/3-запросы могли
завершаться с ошибкой `[alert] sendmsg() failed (90: Message too
large) while sending frames`;
проблема появилась в 1.11.0.
- HTTP/3-запросы не принимались при прослушивании wildcard
IPv6-адреса и включённом BPF;
проблема появилась в 1.11.0.
- При указании доменного имени в директиве [docker_endpoint](https://angie.software//angie/docs/configuration/modules/http/http_docker.md#docker-endpoint)
подключения к Docker API и обновления групп
проксируемых серверов не происходили.
#### Пакеты
- Обновлены:
- [angie-module-cache-purge](https://angie.software//angie/docs/installation/external-modules/cache-purge.md#external-cache-purge) — до версии 2.5.5
02.02.2026
- Обновлены:
- [angie-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.9.5
## 2025
### Angie 1.11.1
Дата выпуска: 30.12.2025.
#### Изменения
- Теперь, если в директиве [acme_http_port](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-http-port) указан
только порт без IP (значение по умолчанию) и есть слушающие на этом
порту блоки `server`, то обработка HTTP-подверждений для
заданного порта в ACME работает только на указанных IP-адресах в
директивах [listen](https://angie.software//angie/docs/configuration/modules/http/index.md#listen) данных блоков; попытки слушать на всех остальных IP,
как было раньше, не производится; это делает настройку более гибкой и
предотвращает возможную проблему при обновлении с предыдущих версий на
конфигурациях, где были только блоки `server`, слушающие на
`80` порту и конкретных IP-адресах.
#### Исправления
- HTTP/2-запросы не учитывались в серверных зонах
статистики; проблема появилась в 1.11.0.
- Если ACME-клиент был отключен в конфигурации и не имел
ранее полученного сертификата, запрос к API статистики для данного
клиента мог привести к падению рабочего процесса.
- Если в качестве ключа директивы [status_zone](https://angie.software//angie/docs/configuration/modules/http/index.md#status-zone), заданной на уровне
блоков `server`, использовались переменные `$http_host` или
`$cookie_*`, то HTTP/3-запросы могли не учитываться в указанной
зоне статистики.
#### Пакеты
- Обновлены:
- [angie-module-vts](https://angie.software//angie/docs/installation/external-modules/vts.md#external-vts) — до версии v0.2.5
### Angie 1.11.0
Дата выпуска: 24.12.2025.
#### Изменения
- Переменная `$http_host` в запросах по протоколу HTTP/3
теперь инициализируется из значения псевдозаголовка `:authority`,
если заголовок `Host` не был передан, что является нормальным для
клиентов; до этого отличия в поведении от протоколов младших версий
могли создавать проблемы в конфигурациях с использованием переменной
`$http_host`.
- Если все HTTP-сервера в `upstream`-группе оказываются
недоступны или возвращают ошибку, то теперь всегда возвращается
собственная страница ошибки вместо принятой от последнего сервера,
когда тот вернул ошибочный статус согласно настройкам директивы
[proxy_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream) (и ей подобных); это позволяет получить
консистентное поведение во всех случаях.
- Параметр `REQUEST_METHOD` в файлах конфигурации
`fastcgi.conf`, `fastcgi_params`, `uwsgi_params` и `scgi_params`
теперь устанавливается через переменную `$upstream_request_method`,
которая принимает значение `GET` для `HEAD`-запросов при настройке
кэширования; это предотвращает проблему, когда ранее в результате
`HEAD`-запроса могло происходить сохранение пустых ответов, которые
затем отдавались на `GET`-запросы, так как в типичной конфигурации
метод запроса не является ключом кэширования.
- Максимальный размер ответа от ACME-сервера теперь
ограничивается директивой [acme_max_response_size](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-max-response-size), а не
параметром `max_cert_size=` директивы [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client); заданного по
умолчанию значения достаточно для большинства случаев, но в случае,
если обновление завершается ошибкой `[error] too big subrequest
response while sending to client`, его следует увеличить.
- Значение по умолчанию директивы [variables_hash_max_size](https://angie.software//angie/docs/configuration/modules/http/index.md#variables-hash-max-size)
в HTTP-модуле увеличено до `2048`, чтобы снизить вероятность появления
предупреждений о неоптимальном построении хэша из-за добавления
множества новых переменных за последние годы: `[warn] could not build
optimal variables_hash, you should increase either
variables_hash_max_size: 1024 or variables_hash_bucket_size: 64;
ignoring variables_hash_bucket_size`.
#### Добавления
- Произвольно конфигурируемый сбор статистики с помощью
нового модуля [Metric](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#http-metric) в HTTP; позволяет, используя различные методы
(счетчики, гистограммы, скользящие средние и др.), агрегировать любые
данные на разных стадиях обработки запроса в реальном времени с
помощью переменных по заданным ключам и отдавать их в секции
`/status/http/metric_zones/` API статистики (с поддержкой
Prometheus), тем самым добавляя встроенный мощный аналитический
инструмент для всего HTTP-трафика.
- Поддержка ALPN-верификации для ACME, задаваемая при
помощи значения `alpn` в качестве параметра `challenge` директивы
[acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client); позволяет запрашивать мультидоменные сертификаты,
держа открытым только HTTPS-порт.
- Информация об ACME-клиентах и процедуре получения
сертификата в разделе `/status/http/acme_clients/` API статистики (с
поддержкой Prometheus).
- Добавлена поддержка Encrypted Client Hello (ECH) в HTTP и
stream SSL-модулях; директива [ssl_encrypted_hello_key](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-encrypted-hello-key) позволяет
задать файл с приватным ключом; переменная `$ssl_encrypted_hello`
содержит информацию об использовании ECH.
Спасибо Максиму Дунину (freenginx).
- Конвертация формата изображения с помощью параметра
`convert` директивы [image_filter](https://angie.software//angie/docs/configuration/modules/http/http_image_filter.md#id3).
- Поддержка форматов AVIF и HEIC в модуле Image Filter.
- Поддержка PROXY-протокола второй версии в stream-модуле в
сторону проксируемых серверов с возможностью передачи произвольных
значений через TLV-записи с помощью директивы
[proxy_protocol_tlv](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-protocol-tlv), в которой можно указывать строки с переменными.
- Переменная `$upstream_request_method`, содержащая метод
запроса к проксируемому серверу, который может отличаться от метода
запроса клиента при использовании кэширования или директивы
[proxy_method](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-method); позволяет легко избежать распространенной проблемы в
конфигурациях, когда на `GET`-запрос возвращается закэшированный пустой
`HEAD`-ответ, а также избежать кэширования `HEAD` и `GET` отдельно.
- Теперь HTTP-верификация в ACME может работать без блоков
`server` с директивой `listen 80` в конфигурации; при необходимости
слушающий порт можно изменить с помощью новой директивы
[acme_http_port](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-http-port).
- Возможность подсчета количества элементов в списках и
объектах при экспорте метрик Prometheus; пути, оканчивающиеся косой
чертой, теперь возвращают количество элементов в соответствующей
коллекции API.
- Переменная `$sent_body`, содержащая тело ответа
подзапроса или запроса от клиентского модуля.
- Поддержка методов аутентификации XOAUTH2 и OAUTHBEARER в
почтовом прокси-сервере.
Спасибо Rob Mueller и Максиму Дунину (freenginx).
- Параметр `route` директивы [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) теперь может
содержать произвольные строки с любым количеством переменных.
- В модуле ACME автоматически вычисляется приблизительный
размер получаемого сертификата, что устраняет необходимость
увеличивать параметр `max_cert_size` директивы [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) в
случаях выпуска сертификата с очень большим количеством доменов;
параметр оставлен для случаев, когда ручная настройка всё же
понадобится.
- Переменная `$upstream_cache_key`, содержащая используемый
ключ кэширования.
Спасибо Кириллу Коринскому и Максиму Дунину (freenginx).
- Поддержка сборки с SSL-библиотекой AWS-LC.
Спасибо Петру Сикоре (piotr at aviatrix.com).
- В Makefile добавлена цель `test`, запускающая тесты.
- Вся функциональность nginx 1.29.3, за исключением
директив `add_header_inherit` и `add_trailer_inherit`, качество
проработки которых крайне низкое.
#### Исправления
- Процедуры перезагрузки конфигурации и обновления
исполняемого файла на лету теперь работают штатно с
HTTP/3-соединениями; реализован корректный роутинг соединений ко всем
существующим процессам при помощи модуля BPF.
- Если все сервера в `upstream`-группе оказывались
недоступны или возвращали ошибку, то ошибочный ответ последнего мог
посчитаться успешным несмотря на настройки директивы
[proxy_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream).
- Когда путь в директиве [try_files](https://angie.software//angie/docs/configuration/modules/http/index.md#try-files) был короче, чем префикс в
соответствующем блоке `location`, использование
[proxy_pass](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) с URI могло приводить к падению рабочего процесса;
исправление портировано из nginx 1.29.4.
- Если в блоке `stream` не было ссылающихся на ACME-клиент
директив `acme`, то при указании в нём соответствующих переменных
`$acme_cert_*` конфигурация не принималась с ошибкой
`unknown variable`; проблема появилась в 1.10.3.
- Если было настроено сохранение индекса кэша в файл,
тестирование конфигурации во время работы могло завершаться ошибками
типа `[alert] mmap() failed (17: File exists)` и
`[alert] munmap() failed (22: Invalid argument)`.
- Директива [proxy_method](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-method) игнорировалась при срабатывании
директивы `proxy_cache_convert_head on`.
- Длительность тайм-аута, задаваемого опцией
`fail_timeout` директивы `server` блока `upstream`, была на 1 секунду
больше, чем указано.
- Angie не собирался на `NetBSD 10.0`.
Спасибо Максиму Дунину (freenginx).
- Загрузка модулей, собранных для Angie PRO, могла
приводить к некорректной работе и падениям из-за несовместимости ABI;
теперь подобные ошибочные конфигурации запрещены, и выдается
соответствующее сообщение об ошибке.
#### Пакеты
- Обновлены:
- [angie-module-echo](https://angie.software//angie/docs/installation/external-modules/echo.md#external-echo) — до версии v0.64
### Angie 1.10.3
Дата выпуска: 13.11.2025.
#### Безопасность
- Обработка специально созданного логина/пароля при
использовании метода аутентификации `none` в SMTP-модуле могла
приводить к отправке серверу аутентификации части содержимого памяти
рабочего процесса ([CVE-2025-53859](https://nvd.nist.gov/vuln/detail/CVE-2025-53859)); исправление портировано из nginx
1.29.1.
#### Исправления
- Если при использовании опции `renew_on_load` директивы
[acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) присутствовал ранее полученный сертификат, то он не
загружался, что могло ограничивать работоспособность до окончания
обновления сертификата; если сертификат отсутствовал, то попытки
получения нового завершались ошибкой `[alert] lseek() failed (9: Bad
file descriptor)`.
- Если [ACME-клиент](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#id4) использовался в блоке `stream`, но не в
блоке `http`, он деактивировался с предупреждением `[warn] ACME
client .. is defined but not used` и не получал сертификата.
- Если все директивы [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) содержали параметр
`enabled=off` и соответствующие переменные `$acme_cert_*`
использовались в конфигурации, то Angie не запускался, сообщая об
ошибке `[emerg] unknown acme_cert_* variable`.
- Если [ACME-клиент](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#id4) использовался в блоке `stream`, который
располагался перед блоком `http`, то Angie не запускался, сообщая об
ошибке `[emerg] ACME client .. is not defined but referenced`.
- Некоторые конфигурации блока `client` могли вызывать
падение рабочих процессов при использовании переменных, связанных с
отсутствующим в данном случае входящим соединением.
#### Пакеты
- Обновлены:
- [angie-module-cache-purge](https://angie.software//angie/docs/installation/external-modules/cache-purge.md#external-cache-purge) — до версии 2.5.4
- [angie-module-cgi](https://angie.software//angie/docs/installation/external-modules/cgi.md#external-cgi) — до версии v0.14.1
- [angie-module-lua](https://angie.software//angie/docs/installation/external-modules/lua.md#external-lua) — до версии 0.10.29
- [angie-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.9.4
---
### Angie 1.10.2
Дата выпуска: 21.08.2025.
#### Исправления
- Настройки прокси-модуля в блоке `http` могли нарушать
работу модулей, которые используют блок `client` для исходящих
запросов; проблема появилась в 1.10.0.
- Включение [proxy_ignore_client_abort](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ignore-client-abort) совместно с
модулями, использующими блок `client` для исходящих запросов, могло
приводить к падению рабочих процессов; проблема появилась в 1.10.0.
- Если в группе проксируемых серверов был ранее
сконфигурирован один сервер, то серверы, добавленные через [Docker
API](https://angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker), могли не участвовать в балансировке.
- Если единственный сервер в группе проксируемых серверов
был добавлен посредством [Docker API](https://angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker),
то в случае признания его недоступным он мог исключаться из балансировки.
#### Пакеты
- Добавлены динамические модули:
- [angie-module-auth-totp](https://angie.software//angie/docs/installation/external-modules/auth-totp.md#external-auth-totp)
- [angie-module-combined-upstreams](https://angie.software//angie/docs/installation/external-modules/combined-upstreams.md#external-combined-upstreams)
- Обновлены:
- [angie-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии 0.41.0
---
### Angie 1.10.1
Дата выпуска: 17.07.2025.
#### Изменения
- Директивы, заданные на уровне блока `client`, теперь могут наследоваться
только в явно объявленных внутри него блоках `location` и не оказывают
влияния на настройки других модулей, неявно использующих блок `client`
для исходящих запросов.
#### Добавления
- Поддержка нескольких блоков `client` позволяет сгруппировать общие
настройки для разных блоков `location` внутри каждого из них, что
помогает избежать дублирования конфигурации.
#### Исправления
- Параметр `reuseport` в директиве `listen` приводил к тому, что все
соединения на указанный адрес и порт обслуживались только одним рабочим
процессом; проблема появилась в версии 1.10.0.
- HTTP/3-согласование с проксируемым сервером могло завершаться ошибкой при
использовании библиотеки OpenSSL версии 3.5.0 или выше, если на сервере был
активен режим `retry` QUIC-протокола.
- Сборка модулей `HTTP/2` и `HTTP/3` компилятором GCC 15 завершалась
ошибкой.
- Сборка компилятором GCC с флагом `-O3` могла завершаться ошибкой.
---
### Angie 1.10.0
Дата выпуска: 03.07.2025.
#### Добавления
- Автоматическое получение и динамическое обновление групп проксируемых серверов
на основе меток Docker-контейнеров (или Podman), настраиваемое с помощью
директивы [docker_endpoint](https://angie.software//angie/docs/configuration/modules/http/http_docker.md#docker-endpoint); это позволяет на указанном Docker API в
реальном времени отслеживать запуск и остановку контейнеров и, соответственно,
добавлять или удалять их адреса из списка `upstream` согласно прописанным
в них специальным меткам и без перезагрузки конфигурации.
- Поддержка автоматического получения TLS-сертификатов по протоколу ACME в
`stream`-модуле, настраиваемое с использованием директивы [acme](https://angie.software//angie/docs/configuration/modules/stream/stream_acme.md#s-acme)
и переменных вида [$acme_cert_\*](https://angie.software//angie/docs/configuration/modules/stream/stream_acme.md#v-s-acme-cert-name) и
[$acme_cert_key_\*](https://angie.software//angie/docs/configuration/modules/stream/stream_acme.md#v-s-acme-cert-key-name).
- Поддержка приема соединений по протоколу MPTCP, включаемая с помощью опции
`multipath` директивы [listen](https://angie.software//angie/docs/configuration/modules/http/index.md#listen).
Спасибо Максиму Дунину (freenginx), Максиму Дурову и Энтони Дорену.
- Блок [client](https://angie.software//angie/docs/configuration/modules/http/index.md#client), позволяющий задавать дополнительную конфигурацию для
внутренних HTTP-запросов, исходящих от различных модулей.
- Вся функциональность [nginx 1.27.5](https://nginx.org/ru/CHANGES.ru),
включая контроль перегрузки CUBIC в соединениях QUIC.
#### Пакеты
- Обновлены:
- [angie-console-light](https://angie.software//angie/docs/installation/oss_packages.md#install-console-light-oss) — до версии 1.8.0
- [angie-module-cgi](https://angie.software//angie/docs/installation/external-modules/cgi.md#external-cgi) — до версии 0.13
- [angie-module-otel](https://angie.software//angie/docs/installation/external-modules/otel.md#external-otel) — до версии 0.1.2
14.07.2025
- Обновлены:
- [angie-module-headers-more](https://angie.software//angie/docs/installation/external-modules/headers-more.md#external-headers-more) — до версии v0.39
- [angie-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs),
[angie-module-njs-light](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.9.1
---
### Angie 1.9.1
Дата выпуска: 29.05.2025.
#### Добавления
- Возможность задать в директиве [acme_dns_port](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-dns-port) не только номер порта, но
и IP-адрес; поддерживаются IPv4 и IPv6.
#### Исправления
- Одновременное наличие в директивах [server_name](https://angie.software//angie/docs/configuration/modules/http/index.md#server-name) wildcard-домена и
совпадающих с ним доменов третьего уровня приводило к ошибке ACME-сервера при
выпуске сертификата для этих доменов в рамках одного ACME-клиента.
- В `stream`-модуле после успешного соединения с проксируемым сервером во
время пассивной проверки его статус в API статистики ошибочно продолжал
отображаться как `unavailable` до завершения сессии.
- Запросы HTTP/3 могли зависать и завершаться по таймауту; исправление
портировано из nginx 1.29.0.
- Ранняя ошибка при установлении соединения HTTP/3 с проксируемым сервером могла
приводить к падению рабочего процесса.
- При проксировании по протоколу HTTP/3 число активных соединений
могло отображаться в статистике некорректно.
#### Пакеты
- Добавлены динамические модули:
- [angie-module-njs-light](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs)
- Обновлены:
- [angie-module-auth-spnego](https://angie.software//angie/docs/installation/external-modules/auth-spnego.md#external-auth-spnego) — до версии 1.1.3
- [angie-module-cgi](https://angie.software//angie/docs/installation/external-modules/cgi.md#external-cgi) — до версии 0.12.1
- [angie-module-modsecurity](https://angie.software//angie/docs/installation/external-modules/modsecurity.md#external-modsec) — до версии 1.0.4
- [angie-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.9.0
- [angie-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии 0.40.0
---
### Angie 1.9.0
Дата выпуска: 11.04.2025.
#### Добавления
- Возможность задать файл в директиве [proxy_cache_path](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path), в который между
запусками сервера будет сохраняться содержимое зоны разделяемой памяти с
индексом кэша; что избавляет от необходимости подгружать кэш после
перезагрузки и позволяет практически сразу вернуть сервер в работу.
- Поддержка механизма TLS 1.3 Early Data (0-RTT) в `stream`-модуле с
помощью директивы [ssl_early_data](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#s-ssl-early-data).
- Новый статус `busy` у проксируемых серверов в API статистики, означающий,
что число запросов на сервер достигло ограничения, заданного опцией
`max_conns`.
- Параметр `uri=` в директиве [acme_hook](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook), который позволяет
переопределять строку запроса к внешнему приложению, в том числе, используя
переменные.
- Параметр `renew_on_load` директивы [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client), позволяющий
форсировать обновление сертификата при загрузке конфигурации.
- Отображение даты и времени сборки в поле `build_time` объекта
`/status/angie` API статистики, а также в выводе ключа командной строки
`-V`.
- Вся функциональность [nginx 1.27.4](https://nginx.org/ru/CHANGES.ru), за
исключением директивы `keepalive_min_timeout` (аналогичный функционал
существует с версии 1.8.0).
#### Изменения
- Параметр `enabled=off` в директиве [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) теперь отключает
только обновление сертификата для данного клиента, но сохраняет весь остальной
функционал; так, остается возможность использовать ключ и сертификат (при
наличии) через переменные `$acme_cert_*`, а использование переменных
`$acme_hook_*` и директив `acme` не приводит к ошибкам.
- Ошибка `no valid domain name defined for ACME client` теперь возникает
только если на ACME-клиент есть ссылка из директивы `acme` в блоке
`server`, но ни один из доменов этого сервера не соответствует требованиям
ACME.
#### Исправления
- При сборке с поддержкой NTLS наследование директив
`proxy_ssl_certificate` и `proxy_ssl_certificate_key` с
переменными работало некорректно.
#### Пакеты
- Обновлены:
- [angie-module-cgi](https://angie.software//angie/docs/installation/external-modules/cgi.md#external-cgi) — до версии 0.11.1
- [angie-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.8.10
---
### Angie 1.8.3
Дата выпуска: 02.04.2025.
#### Исправления
- Статистика [status_zone](https://angie.software//angie/docs/configuration/modules/http/index.md#status-zone) в блоке [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server) HTTP-модуля могла
считаться некорректно, если запросы попадали в разные зоны статистики в рамках
одного соединения или на раннем этапе обработки запроса происходила ошибка;
проблема появилась в 1.8.2.
#### Пакеты
- Обновлены:
- [angie-console-light](https://angie.software//angie/docs/installation/oss_packages.md#install-console-light-oss) — до версии 1.7.0
- [angie-module-cgi](https://angie.software//angie/docs/installation/external-modules/cgi.md#external-cgi) — до версии 57f660bb2c6ef6e4b75c65406080d0236860ca08
- [angie-module-jwt](https://angie.software//angie/docs/installation/external-modules/jwt.md#external-jwt) — до версии v3.4.3
- [angie-module-ndk](https://angie.software//angie/docs/installation/external-modules/ndk.md#external-ndk) — до версии v0.3.4
- [angie-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии v0.39.0
- [angie-module-vts](https://angie.software//angie/docs/installation/external-modules/vts.md#external-vts) — до версии v0.2.4
04.04.2025
- Обновлены:
- [angie-console-light](https://angie.software//angie/docs/installation/oss_packages.md#install-console-light-oss) — до версии 1.7.1
07.04.2025
- Обновлены:
- [angie-console-light](https://angie.software//angie/docs/installation/oss_packages.md#install-console-light-oss) — до версии 1.7.2
### Angie 1.8.2
Дата выпуска: 13.02.2025.
#### Безопасность
- Недостаточная проверка в обработке виртуальных серверов при использовании SNI
в TLSv1.3 позволяла повторно использовать SSL-сессию в контексте другого
виртуального сервера, обходя проверку клиентских SSL-сертификатов
([CVE-2025-23419](https://www.cve.org/CVERecord?id=CVE-2025-23419));
исправление портировано из nginx 1.27.4.
#### Исправления
- Запросы к API для получения значений статистики из отдельной зоны, которая
была задана через переменные, могли приводить к зацикливанию рабочего
процесса.
- HTTP/3-запросы не учитывались в зонах статистики; проблема появилась в 1.8.0.
- TLS-согласования по протоколу QUIC не учитывались в статистике по SSL.
- Использование доменных имен, начинающихся с точки, в директиве
[server_name](https://angie.software//angie/docs/configuration/modules/http/index.md#server-name), могло привести к ошибке обновления сертификата по
[протоколу ACME](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#id4).
#### Пакеты
- Добавлены динамические модули:
- [angie-module-auth-pam](https://github.com/sto/ngx_http_auth_pam_module)
- [angie-module-cgi](https://github.com/pjincz/nginx-cgi)
---
## 2024
### Angie 1.8.1
Дата выпуска: 28.12.2024.
#### Исправления
- Использование директивы [status_zone](https://angie.software//angie/docs/configuration/modules/http/index.md#status-zone) в блоке `server` HTTP-модуля
приводило к избыточному логированию пустых запросов в [access_log](https://angie.software//angie/docs/configuration/modules/http/http_log.md#access-log) во
время TLS-согласований; проблема появилась в 1.8.0.
- Ошибки декодирования потока HTTP/3 могли приводить к падению рабочего процесса
при закрытии QUIC-соединения; исправление портировано из nginx 1.27.4.
- Отправка пакетов с согласованием версии протокола QUIC могла привести к
бесконечному циклу обмена пакетами; исправление портировано из nginx 1.27.4.
- Использование DNS-валидации без хуков в [ACME-модуле](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) на
некоторых конфигурациях могло привести к падению рабочего процесса.
#### Пакеты
- Обновлены:
- [angie-module-auth-jwt](https://angie.software//angie/docs/installation/oss_packages.md#install-dynamicmodules-oss) — до версии 0.9.0
23.01.2025
- Обновлены:
- [angie-console-light](https://angie.software//angie/docs/installation/oss_packages.md#install-console-light-oss) — до версии 1.6.0
27.01.2025
- Добавлены динамические модули:
- [angie-module-unbrotli](https://github.com/clyfish/ngx_unbrotli)
- Обновлены:
- [angie-console-light](https://angie.software//angie/docs/installation/oss_packages.md#install-console-light-oss) — до версии 1.6.1
- [angie-module-auth-spnego](https://angie.software//angie/docs/installation/external-modules/auth-spnego.md#external-auth-spnego) — до версии v1.1.2
- [angie-module-headers-more](https://angie.software//angie/docs/installation/external-modules/headers-more.md#external-headers-more) — до версии v0.38
- [angie-module-lua](https://angie.software//angie/docs/installation/external-modules/lua.md#external-lua) — до версии 0.10.28
- [angie-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.8.9
- [angie-module-vts](https://angie.software//angie/docs/installation/external-modules/vts.md#external-vts) — до версии v0.2.3
- [angie-module-wasm](https://angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-core) — до версии v0.2-beta2
---
### Angie 1.8.0
Дата выпуска: 19.12.2024.
#### Добавления
- Поддержка валидации `DNS-01` посредством ответа на DNS-запрос от
ACME-сервера, что позволяет автоматически запрашивать сертификаты любых типов,
в том числе wildcard.
- Система внешних вызовов в модуле ACME, настраиваемая с помощью директивы
[acme_hook](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook), которая позволяет обеспечить валидацию доменных имен
посредством внешнего обработчика для интеграции с различными сервисами и
провайдерами DNS-хостинга.
- ACME-модуль выводит в лог дополнительную информацию: точная причина обновления
сертификата, полный список доменов, идентификатор аккаунта пользователя,
длительные периоды неактивности (например, во время опросов), какой домен
выполняет валидацию. Такая информация позволяет легче диагностировать проблемы
на этапе перевыпуска сертификатов, а также прописывать DNS-запись CAA.
- Параметр `account_key` в директиве [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client), позволяющий
переиспользовать существующий ключ аккаунта ACME-сервера, а не генерировать
новый автоматически.
- Поддержка переменных в директиве [status_zone](https://angie.software//angie/docs/configuration/modules/http/index.md#status-zone) в модулях HTTP и stream
позволяет динамически распределять статистику по нескольким зонам в рамках
одного блока `location` или `server`. Это, в частности, пригодится
для случая, когда один блок `server` обрабатывает несколько виртуальных
хостов.
- Совместимость HTTP-модуля сжатия GZip с версиями библиотеки `zlib-ng`
2.2.0 и выше, которые ранее могли приводить к появлению в логе ошибок вида
`[alert] gzip filter failed to use preallocated memory`.
- Директива [max_headers](https://angie.software//angie/docs/configuration/modules/http/index.md#max-headers), ограничивающая максимальное количество полей
заголовка в HTTP-запросе для лучшей защиты от DoS-атак. Спасибо Максиму Дунину
(freenginx) и Максиму Евменкину.
- Директивы [http3_max_table_capacity](https://angie.software//angie/docs/configuration/modules/http/http_v3.md#http3-max-table-capacity) и
[proxy_http3_max_table_capacity](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-max-table-capacity) для настройки ограничения на размер
динамической таблицы сжатия заголовка в HTTP/3.
- Поддержка кросс-компиляции — система сборки теперь может использовать
скрипт-обертку для запуска автотестов, что позволяет подготовить сборку без
запуска тестовых программ непосредственно на целевой платформе.
- Вся функциональность [nginx 1.27.3](https://nginx.org/ru/CHANGES.ru).
#### Исправления
- HTTP/3-клиенты могли отключаться по таймауту при использовании `0-RTT`.
Проблема была унаследована из nginx в версии 1.7.0.
- Проксирование по HTTP/3 с использованием переменных в директиве
[proxy_pass](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) и без указания блока `upstream` могло приводить к
падению рабочего процесса.
- Кэширование HTTP/3-ответов при использовании динамической таблицы сжатия
заголовка могло привести к падению рабочего процесса.
- Некоторые SSL-рукопожатия могли не учитываться в счетчиках статистики для
stream-модуля.
- Настройки HTTP/3-проксирования, указанные на уровне `http` или
`server`, могли игнорироваться.
- При проксировании по протоколу HTTP/3 с включенной поддержкой NTLS директива
[proxy_ssl_certificate](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-certificate) не работала.
#### Изменения
- При плавном завершении старых рабочих процессов keepalive-соединения теперь
закрываются только после истечения таймаута, заданного директивой
[lingering_timeout](https://angie.software//angie/docs/configuration/modules/http/index.md#lingering-timeout). Такое поведение позволяет предотвратить возможные
ошибки на клиенте при получении ответа в этот момент. Спасибо Максиму Дунину
(freenginx).
- Отключено кэширование значений переменных stream-модуля
[$ssl_server_name](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-server-name), [$ssl_server_cert_type](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-server-cert-type),
[$ssl_preread_protocol](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#v-ssl-preread-protocol) и [$ssl_preread_server_name](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#v-ssl-preread-server-name), что
позволит получить актуальные значения при использовании виртуальных серверов.
#### Пакеты
- Добавлены динамические модули:
- [angie-module-http-auth-radius](https://github.com/ten0s/ngx_http_auth_radius_module)
- Обновлены:
- [angie-module-auth-jwt](https://angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) — до версии 0.8.0
- [angie-module-jwt](https://angie.software//angie/docs/installation/external-modules/jwt.md#external-jwt) — до версии 3.4.2
- [angie-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.8.8
- [angie-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии 0.38.0
- [angie-module-wasm](https://angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-core) — до версии 0.1-beta5
---
### Angie 1.7.0
Дата выпуска: 19.09.2024.
#### Добавления
- Принудительное закрытие соединений к проксируемому серверу при удалении его из
группы, настраиваемое с помощью директив [proxy_connection_drop](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-connection-drop),
[grpc_connection_drop](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-connection-drop), [fastcgi_connection_drop](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-connection-drop),
[scgi_connection_drop](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-connection-drop) и [uwsgi_connection_drop](https://angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-connection-drop).
- Счетчики отдельных типов отправленных DNS-запросов в API
статистики резолвера, собираемой параметром `status_zone` директивы
[resolver](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver).
- Переменная [$ssl_server_cert_type](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-server-cert-type), содержащая тип выбранного
сертификата при приеме TLS-соединения.
- Отключение создания PID-файла с помощью параметра `off` в директиве
[pid](https://angie.software//angie/docs/configuration/modules/core.md#pid), что может быть полезным для неизменяемых образов и при
непосредственном управлении менеджером процессов. Спасибо Максиму Дунину
(freenginx).
- Создание PID-файла теперь выполняется атомарно через
промежуточный временный файл, что исключает момент, когда файл уже
появился в директории, но еще пуст, и позволяет внешним программам
проще и надежнее с ним работать.
- Теперь при переконфигурации не делается попытка пересоздать PID-файл, если имя
в директиве [pid](https://angie.software//angie/docs/configuration/modules/core.md#pid) изменилось, но указывает на тот же файл через симлинки,
что, в частности, позволяет избежать проблем в системах во время миграции с
`/var/run/angie.pid` на `/run/angie.pid`. Спасибо Максиму Дунину
(freenginx).
- Ошибки [записи в syslog](https://angie.software//angie/docs/configuration/processing.md#syslog-logging) теперь логгируются не чаще
одного раза в секунду, что помогает предотвратить засорение логов подобными
сообщениями в случаях перегрузки или сбоя syslog-сервера. Спасибо Максиму
Дунину (freenginx).
- В почтовом прокси-сервере ограничено максимальное количество команд в процессе
аутентификации, задаваемое директивой [max_commands](https://angie.software//angie/docs/configuration/modules/mail/index.md#max-commands), для улучшения
защиты против DoS-атак. Спасибо Максиму Дунину (freenginx).
- Опция [--feature-cache](https://angie.software//angie/docs/installation/sourcebuild.md#configure) скрипта **./configure** для
кэширования результатов его работы с целью оптимизации массовой сборки модулей
или кросс-компиляции.
- Вся функциональность [nginx 1.27.1](https://nginx.org/ru/CHANGES.ru).
#### Исправления
- При запуске под systemd могли возникать ошибки `PID file ... not
readable (yet?) after start` и `Failed to parse PID from file...`.
Спасибо Максиму Дунину (freenginx).
#### Изменения
- Обновлены текстовые описания кодов HTTP-ответов в соответствии с RFC 9110.
Спасибо Максиму Дунину (freenginx) и Michiel W. Beijen.
- Теперь перед HTTP-запросом допускается не более одной пустой строки для
улучшения защиты против DoS-атак. Спасибо Максиму Дунину (freenginx).
- Запрещены имена полей заголовка HTTP/1.x без двоеточия на конце; такие
некорректные заголовки от клиента или проксируемого сервера теперь будут
приводить к возврату ошибки. Спасибо Максиму Дунину (freenginx) и Максиму
Евменкину.
- При чтении тела запроса с использованием HTTP/1.1 "chunked transfer encoding"
суммарный размер игнорируемых "chunk extensions" и полей "trailer header"
теперь ограничен директивой [client_max_body_size](https://angie.software//angie/docs/configuration/modules/http/index.md#client-max-body-size) для улучшения защиты
против DoS-атак. Спасибо Максиму Дунину (freenginx) и Bartek Nowotarski.
- MIME-тип в файле конфигурации `mime.types` для расширения `bmp` изменен
на `image/bmp`, для расширения `rar` u2014 на
`application/vnd.rar`, а для расширений `deb` и `udeb`
теперь указан `application/vnd.debian.binary-package`. Спасибо Юрию
Изоркину.
#### Пакеты
- Обновлены:
- [angie-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии 0.36.0
- [angie-module-lua](https://angie.software//angie/docs/installation/external-modules/lua.md#external-lua) — до версии 0.10.27
24.10.2024
- Пакеты для операционной системы [SberLinux](https://angie.software//angie/docs/installation/oss_packages.md#install-yum-oss).
29.11.2024
- Добавлена поддержка WASM с использованием следующих пакетов:
- [angie-module-wamr](https://angie.software//angie/docs/configuration/modules/wasm/wasm_wamr.md#wasm-wamr)
- [angie-module-wasm](https://angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-core)
- [angie-module-wasmtime](https://angie.software//angie/docs/configuration/modules/wasm/wasm_wasmtime.md#wasm-wasmtime)
---
### Angie 1.6.2
Дата выпуска: 16.08.2024.
#### Безопасность
- Обработка специально созданного MP4-файла модулем
[ngx_http_mp4_module](https://angie.software//angie/docs/configuration/modules/http/http_mp4.md#http-mp4)
могла приводить к падению рабочего процесса
([CVE-2024-7347](https://nvd.nist.gov/vuln/detail/CVE-2024-7347));
исправление портировано из nginx 1.27.1.
---
### Angie 1.6.1
Дата выпуска: 08.08.2024.
#### Добавления
- Счетчик `passed` в зоне
[API статистики](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-server-zones), задаваемой
директивой [status_zone](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone) модуля [stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream),
для подсчета соединений, переданных на обработку в другие слушающие сокеты
при помощи директив [pass](https://angie.software//angie/docs/configuration/modules/stream/stream_pass.md#s-pass).
#### Исправления
- При использовании виртуальных серверов или директивы [pass](https://angie.software//angie/docs/configuration/modules/stream/stream_pass.md#s-pass)
в модуле [stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream)
соединения могли учитываться некорректно в API статистики.
- На конфигурациях с 5 ACME-клиентами и более могли
происходить падения рабочих процессов; проблема появилась в 1.6.0.
- Обработка закэшированных ответов с заголовком
`X-Accel-Redirect` могла приводить к падению рабочего процесса.
Спасибо Максиму Дунину (freenginx) и Иржи Сетничке.
#### Пакеты
- Обновлены:
- [angie-console-light](https://angie.software//angie/docs/installation/oss_packages.md#install-console-light-oss) — до версии 1.4.0
- [angie-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии 0.35.3
- [angie-module-zstd](https://angie.software//angie/docs/installation/external-modules/zstd.md#external-zstd) — до ревизии `f4ba115`
---
### Angie 1.6.0
Дата выпуска: 28.06.2024.
#### Добавления
- Директива [sticky](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky) и сопутствующие настройки в блоке
[upstream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) [stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream)-модуля,
позволяющие задать режим привязки сессий,
при котором все соединения в рамках сессии
будут направляться на один и тот же сервер.
- Извлечение значений Cookie из RDP-соединений с помощью
директивы [rdp_preread](https://angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#s-rdp-preread) [stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream)-модуля
в переменные [$rdp_cookie](https://angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#v-rdp-cookie) и
[$rdp_cookie_NAME](https://angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#id5),
что позволяет логировать и привязывать RDP-сеансы клиентов
к одним и тем же серверам при балансировке нагрузки.
- Возможность указать несколько директив [acme](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#id4)
в одном блоке [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server),
что позволяет настраивать получение сертификатов сразу двух типов
в рамках данного виртуального сервера.
- Ключи командной строки `-m` и `-M`
для отображения списка встроенных и загруженных модулей.
- Поддержка [BoringSSL](https://www.chromium.org/Home/chromium-security/boringssl/)
в модуле [ACME](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme).
- Вся функциональность [nginx 1.27.0](https://nginx.org/ru/CHANGES.ru),
включая поддержку виртуальных серверов в модуле [stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream)
и директиву `pass`,
позволяющую передавать принятые соединения на обработку в другие слушающие сокеты,
в том числе модулей [HTTP](https://angie.software//angie/docs/configuration/modules/index.md#modules-http) и [Mail](https://angie.software//angie/docs/configuration/modules/index.md#modules-mail).
#### Исправления
- Запрос сертификата по протоколу ACME мог завершаться ошибкой
в некоторых конфигурациях с сообщением в логе вида
`[alert] getsockname() failed (9: Bad file descriptor)`.
- Запрос сертификата с большим количеством доменных имен по протоколу ACME
мог завершаться ошибкой с сообщением в логе вида
`[error] JSON parser error`.
- ACME-клиенты в конфигурациях с несколькими директивами
[error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log)
могли выводить сообщения в несоответствующие логи.
#### Пакеты
- Обновлены:
- [angie-module-auth-jwt](https://angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) — до версии 0.7.0
- [angie-module-auth-ldap](https://angie.software//angie/docs/installation/external-modules/auth-ldap.md#external-ldap) — до ревизии `241200e`
- [angie-module-jwt](https://angie.software//angie/docs/installation/external-modules/jwt.md#external-jwt) — до версии 3.4.1
- [angie-module-keyval](https://angie.software//angie/docs/installation/external-modules/keyval.md#external-keyval) — до версии 0.3.0
- [angie-module-lua](https://angie.software//angie/docs/installation/external-modules/lua.md#external-lua):
`stream_lua_module` — до ревизии `bea8a0c`
- [angie-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.8.5
---
### Angie 1.5.2
Дата выпуска: 03.06.2024.
#### Безопасность
- При использовании HTTP/3 обработка специально созданной
QUIC-сессии могла приводить к падению рабочего процесса, отправке
клиенту содержимого памяти рабочего процесса на системах с MTU больше
4096 байт и иметь другие последствия
([CVE-2024-32760](https://nvd.nist.gov/vuln/detail/CVE-2024-32760),
[CVE-2024-31079](https://nvd.nist.gov/vuln/detail/CVE-2024-31079),
[CVE-2024-35200](https://nvd.nist.gov/vuln/detail/CVE-2024-35200),
[CVE-2024-34161](https://nvd.nist.gov/vuln/detail/CVE-2024-34161));
исправление портировано из nginx 1.26.1.
#### Пакеты
- Обновлены:
- [angie-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии 0.35.2
---
### Angie 1.5.1
Дата выпуска: 16.05.2024.
#### Исправления
- Механизм `proxy_next_upstream` работал некорректно при
использовании опции [resolve](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-reresolve) директивы `server` в блоке `upstream`,
если количество полученных IP-адресов отличалось от числа заданных
серверов.
- При запросе сертификата по протоколу ACME могла
произойти ошибка сегментации в рабочем процессе.
- Механизм [slow_start](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-slow-start) не срабатывал при проксировании
TCP-соединений в модуле [stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream).
- Запросы HTTP/3 могли завершаться с ошибкой, если они
были присланы как TLS 1.3 early data; проблема появилась в 1.4.0.
- HTTP/3-соединение могло закрываться преждевременно при
использовании 0-RTT в QUIC.
- При чтении тела запроса из быстрого соединения было
возможно чтение в течение долгого времени. Спасибо Максиму Дунину
(freenginx).
#### Изменения
- Теперь ACME-клиенты не игнорируют ранее сохраненные
сертификаты, если они просрочены или выпущены для отличающегося
списка доменных имен, а используют их, пока идет обновление.
#### Пакеты
27.05.2024
- Пакеты для операционной системы [Alpine](https://angie.software//angie/docs/installation/oss_packages.md#install-alpine-oss) 3.20.
---
### Angie 1.5.0
Дата выпуска: 27.03.2024.
#### Добавления
- Начальная поддержка автоматического получения и обновления сертификатов по
[протоколу ACME](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme), конфигурируемая с
помощью директив [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) и [acme](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#id4), а также переменных вида
[$acme_cert_=](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-name) и [$acme_cert_key_=](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-key-name).
- Настройка автоматического перенаправления для добавления
слеша в конец URI запроса с помощью директивы [auto_redirect](https://angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect).
- Вывод содержащих даты [метрик](https://angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) в формате временных меток Unix
вместо ISO 8601 для использования в Prometheus, а также в JSON API при запросе
с аргументом `?date-epoch`.
- Новый статус `recovering` у проксируемых серверов в [API статистики](https://angie.software//angie/docs/configuration/modules/http/http_api.md#metrics), означающий, что сервер медленно восстанавливается после сбоя
согласно опции `slow_start`.
- Теперь ключ `-V` показывает также релевантную версию nginx, что
полезно для совместимости со сторонними утилитами, в частности
**certbot**. Спасибо [AdvTechnoKing](https://github.com/webserver-llc/angie/commit/eb914d43aa6a2231d7321c808cb4180abb013ca0).
- Вся функциональность [nginx 1.25.4](https://nginx.org/ru/CHANGES.ru).
#### Исправления
- Если был задействован механизм переиспользования SSL-сессий
([proxy_ssl_session_reuse](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-session-reuse)), то при динамическом обновлении списка
проксируемых серверов могла происходить утечка из зоны разделяемой памяти
(`zone`), настроенной для соответствующего блока `upstream`.
#### Пакеты
- Пакеты для операционных систем [FreeBSD 13](https://angie.software//angie/docs/installation/oss_packages.md#install-freebsd-oss) (arm64),
[RED OS 8](https://angie.software//angie/docs/installation/oss_packages.md#install-yum-oss) (x86-64).
- Добавлены динамические модули:
- [angie-module-otel](https://github.com/nginxinc/nginx-otel)
- Обновлены:
- [angie-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии 0.34.0
28.03.2024
- Обновлены:
- [angie-console-light](https://angie.software//angie/docs/installation/oss_packages.md#oss-packages) — до версии 1.3.0
16.04.2024
- Добавлены динамические модули:
- [angie-module-zstd](https://github.com/tokers/zstd-nginx-module)
- Обновлены:
- [angie-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.8.4
25.04.2024
- Добавлены динамические модули:
- angie-module-vts: включает
[module-vts](https://github.com/vozlt/nginx-module-vts),
[module-sts](https://github.com/vozlt/nginx-module-sts),
[module-stream-sts](https://github.com/vozlt/nginx-module-stream-sts)
---
### Angie 1.4.1
Дата выпуска: 15.02.2024.
#### Безопасность
- При использовании HTTP/3 в рабочем процессе во время обработки специально
созданной QUIC-сессии могла произойти ошибка сегментации
([CVE-2024-24989](https://nvd.nist.gov/vuln/detail/CVE-2024-24989));
при этом Angie, начиная еще с версии 1.4.0, не подвержен уязвимости
[CVE-2024-24990](https://nvd.nist.gov/vuln/detail/CVE-2024-24990).
#### Пакеты
- Добавлены динамические модули:
- [angie-module-dynamic-limit-req](https://github.com/limithit/ngx_dynamic_limit_req_module)
- Обновлены:
- [angie-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.8.3
- [angie-module-vod](https://angie.software//angie/docs/installation/external-modules/vod.md#external-vod) — до версии 1.33
## 2023
### Angie 1.4.0
Дата выпуска: 12.12.2023.
#### Добавления
- Поддержка HTTP/3-соединений с upstream-серверами в
[прокси-модуле HTTP](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy),
допускающая использование клиентами произвольных версий HTTP.
Конфигурация осуществляется с помощью директивы [proxy_http_version](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version)
и набора директив `proxy_quic_` и `proxy_http3_`.
- Механизм плавного ввода проксируемого сервера в работу после сбоя
с помощью опции `slow_start` директивы [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server)
в блоке [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream).
- Директива [mqtt_preread](https://angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#s-mqtt-preread) модуля [stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream),
позволяющая помещать имя пользователя и идентификатор клиента
из пакета CONNECT протокола MQTT в переменные
[$mqtt_preread_username](https://angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#v-mqtt-preread-username) и [$mqtt_preread_clientid](https://angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#v-mqtt-preread-clientid).
- Ограничение скорости отдачи MP4-файлов клиенту
пропорционально битрейту
с помощью директив [mp4_limit_rate](https://angie.software//angie/docs/configuration/modules/http/http_mp4.md#mp4-limit-rate) и [mp4_limit_rate_after](https://angie.software//angie/docs/configuration/modules/http/http_mp4.md#mp4-limit-rate-after),
снижающее нагрузку на полосу пропускания.
- Вся функциональность [nginx 1.25.3](https://nginx.org/ru/CHANGES.ru).
#### Исправления
- Если проксируемый сервер был единственным в группе, то
он мог некорректно учитываться как `unavailable` в
[API статистики](https://angie.software//angie/docs/configuration/modules/http/http_api.md#metrics)
даже после восстановления работоспособности.
#### Пакеты
- Пакеты для операционной системы [Alpine](https://angie.software//angie/docs/installation/oss_packages.md#install-alpine-oss) 3.19.
- Добавлены динамические модули:
- [angie-module-auth-ldap](https://github.com/kvspb/nginx-auth-ldap)
- Обновлены:
- [angie-module-auth-jwt](https://angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) — до версии 0.4.0
- [angie-module-headers-more](https://angie.software//angie/docs/installation/external-modules/headers-more.md#external-headers-more) — до версии 0.36
- [angie-module-ndk](https://angie.software//angie/docs/installation/external-modules/ndk.md#external-ndk) — до версии 0.3.3
- [angie-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии 0.33.0
18.12.2023
- Обновлены:
- [angie-console-light](https://angie.software//angie/docs/installation/oss_packages.md#oss-packages) — до версии 1.2.0
25.12.2023
- Обновлены:
- [angie-console-light](https://angie.software//angie/docs/installation/oss_packages.md#oss-packages) — до версии 1.2.1
22.01.2024
- Добавлены динамические модули:
- [angie-module-zip](https://github.com/evanmiller/mod_zip)
- Обновлены:
- [angie-module-auth-jwt](https://angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) — до версии 0.6.0
- [angie-module-headers-more](https://angie.software//angie/docs/installation/external-modules/headers-more.md#external-headers-more) — до версии 0.37
- [angie-module-lua](https://angie.software//angie/docs/installation/external-modules/lua.md#external-lua):
`http_lua_module` — до версии 0.10.26;
`stream_lua_module` — до версии 0.0.14
---
### Angie 1.3.2
Дата выпуска: 23.11.2023.
#### Исправления
- Были возможны некорректные значения метрик в формате [Prometheus](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#id3), в значениях которых использовались отличные от `$p8s_value`
переменные; на практике проблема могла наблюдаться с
`angie_http_upstreams_peers_state` и `angie_stream_upstreams_peers_state`
из стандартного шаблона `prometheus_all.conf`.
- Некоторые попытки соединения с проксируемыми серверами могли не учитываться
соответствующим образом в [API статистики](https://angie.software//angie/docs/configuration/modules/http/http_api.md#a-api), если ошибка
происходила моментально; проблема появилась в 1.3.0.
#### Пакеты
04.12.2023
- Добавлены динамические модули:
- [angie-module-modsecurity](https://github.com/owasp-modsecurity/ModSecurity-nginx)
07.12.2023
- Обновлены:
- [angie-console-light](https://angie.software//angie/docs/installation/oss_packages.md#oss-packages) — до версии 1.1.1
---
### Angie 1.3.1
Дата выпуска: 18.10.2023.
#### Безопасность
- Добавлены дополнительные ограничения при обработке потоков HTTP/2, чтобы
лучше противостоять DoS-атаке "HTTP/2 Rapid Reset" ([CVE-2023-44487](https://nvd.nist.gov/vuln/detail/CVE-2023-44487)).
#### Пакеты
26.10.2023
- Добавлены динамические модули:
- [angie-module-opentracing](https://github.com/opentracing-contrib/nginx-opentracing/)
13.11.2023
- Добавлены динамические модули:
- [angie-module-testcookie](https://github.com/kyprizel/testcookie-nginx-module/)
- Обновлены:
- [angie-console-light](https://angie.software//angie/docs/installation/oss_packages.md#oss-packages) — до версии 1.1.0
- [angie-module-headers-more](https://angie.software//angie/docs/installation/external-modules/headers-more.md#external-headers-more) — до версии 0.35
- [angie-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.8.2
- [angie-module-vod](https://angie.software//angie/docs/installation/external-modules/vod.md#external-vod) — до версии 1.32
---
### Angie 1.3.0
Дата выпуска: 19.09.2023.
#### Добавления
- Возможность указывать в директиве `location` несколько строк для
сопоставления, что позволяет [объединить](https://angie.software//angie/docs/configuration/modules/http/index.md#combined-locations) несколько
блоков `location` с одинаковыми настройками и, таким образом, упростить
конфигурацию за счет уменьшения дублирования.
- Экспорт различных метрик статистики в формате Prometheus
с гибко настраиваемыми шаблонами при помощи новых директив
[prometheus](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#id3) и [prometheus_template](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#prometheus-template).
- Детальная информация и [метрики](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-upstreams) по
группам проксируемых stream-серверов в интерфейсе статистики, предоставляемом
директивой [api](https://angie.software//angie/docs/configuration/modules/http/http_api.md#a-api).
- Опция [resolve](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-reresolve) директивы `server` в блоке `upstream`
модуля [stream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream), позволяющая отслеживать изменения
списка IP-адресов, соответствующего доменному имени, и автоматически
обновлять его без перезагрузки конфигурации.
- Опция [service](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-reresolve) директивы `server` в блоке `upstream`
модуля [stream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream), позволяющая получать списки адресов
из DNS-записей SRV, с базовой поддержкой приоритета.
- Получение содержимого конфигурационных файлов, с которыми
было запущено текущее поколение рабочих процессов, в интерфейсе,
предоставляемом директивой [api](https://angie.software//angie/docs/configuration/modules/http/http_api.md#a-api) при включении директивы
[api_config_files](https://angie.software//angie/docs/configuration/modules/http/http_api.md#a-api-config-files).
- Отображение номера [поколения конфигурации](https://angie.software//angie/docs/configuration/runtime.md#control-config-change) в
именах процессов, что позволяет с помощью утилиты `ps` отслеживать успех
перезагрузок конфигурации и количество поколений рабочих процессов с
предыдущими версиями конфигурации.
- Вся функциональность [nginx 1.25.2](https://nginx.org/ru/CHANGES.ru).
#### Исправление
- Сборка завершалась ошибкой при использовании опций
`./configure` `--without-http_upstream_zone_module` или
`--without-stream_upstream_zone_module`; ошибка появилась в 1.2.0.
#### Изменения
- Теперь при загрузке конфигурации OpenSSL используется
appname `angie`.
#### Пакеты
- Обновлены:
- [angie-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.8.1.
---
### Angie 1.2.0
Дата выпуска: 30.05.2023.
#### Добавления
- Директива [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) и сопутствующие настройки в блоке [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream)
[HTTP](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream)-модуля, позволяющие задать режим привязки сессий,
при котором все запросы в рамках сессии будут направляться на один и тот же
сервер.
- Переменная [$upstream_sticky_status](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-sticky-status), принимающая значения `NEW`,
`HIT` или `MISS` в зависимости от успеха направления запроса на
релевантный проксируемый сервер с включенной привязкой сессий.
- Поддержка NTLS в [HTTP](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#stream-ssl) модулях
при использовании TLS библиотеки [TongSuo](https://github.com/Tongsuo-Project/Tongsuo), включаемая опцией сборки
`‑‑with‑ntls` и настраиваемая с помощью соответствующих директив
[ssl_ntls](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ntls) и [proxy_ssl_ntls](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-ntls).
- В [HTTP](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#stream-proxy) прокси-модулях
теперь можно настраивать несколько сертификатов разного типа (RSA и ECDSA) и
соответствующих им ключей, используя директивы [proxy_ssl_certificate](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-certificate) и
[proxy_ssl_certificate_key](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-certificate-key).
- Вывод версии и сборки в отображаемом имени `master` процесса, что позволяет
с помощью утилиты `ps` получить эту информацию о работающем экземпляре
сервера.
- Возможность сжатия модулем [gzip](https://angie.software//angie/docs/configuration/modules/http/http_gzip.md#http-gzip) ответов со статусом "207
Multi-Status". Спасибо
[DBotThePony](https://github.com/webserver-llc/angie/pull/26).
- Вся функциональность [nginx 1.25.0](https://nginx.org/ru/CHANGES.ru),
включая поддержку [HTTP/3](https://angie.software//angie/docs/configuration/modules/http/http_v3.md#http-v3).
#### Пакеты
- Пакеты для операционной системы [Ubuntu 23.04 "Lunar Lobster"](https://angie.software//angie/docs/installation/oss_packages.md#install-deb-oss).
- Пакеты динамических модулей:
- Пакет `angie-module-lua` включает
[http_lua_module](https://github.com/openresty/lua-nginx-module)
и
[stream_lua_module](https://github.com/openresty/stream-lua-nginx-module).
- [angie-module-redis2](https://github.com/openresty/redis2-nginx-module)
13.06.2023
- Пакеты для операционных систем [Debian 12 "Bookworm"](https://angie.software//angie/docs/installation/oss_packages.md#install-deb-oss) и
[AlmaLinux](https://angie.software//angie/docs/installation/oss_packages.md#install-yum-oss).
12.07.2023
- Добавлены динамические модули:
- [angie-module-cache-purge](https://github.com/nginx-modules/ngx_cache_purge)
- [angie-module-echo](https://github.com/openresty/echo-nginx-module)
- [angie-module-keyval](https://github.com/kjdev/nginx-keyval)
- [angie-module-postgres](https://github.com/FRiCKLE/ngx_postgres)
- Обновлены:
- [angie-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.8.0.
28.07.2023
- Добавлены динамические модули:
- [angie-module-auth-jwt](https://github.com/kjdev/nginx-auth-jwt)
18.08.2023
- Добавлены динамические модули:
- [angie-module-enhanced-memcached](https://github.com/bpaquet/ngx_http_enhanced_memcached_module)
- [angie-module-eval](https://github.com/openresty/nginx-eval-module)
---
### Angie 1.1.0
Дата выпуска: 24.01.2023.
#### Добавления
- Опция [resolve](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) директивы [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) в блоке
[upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) [HTTP](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream)-модуля, позволяющая отслеживать
изменения списка IP-адресов, соответствующего доменному имени, и
автоматически обновлять его без перезагрузки конфигурации.
- Опция [service](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) директивы [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) в блоке
[upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) [HTTP](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream)-модуля, позволяющая получать
списки адресов из DNS SRV записей, с базовой поддержкой приоритета.
- [Детальная информация и метрики](https://angie.software//angie/docs/configuration/modules/http/http_api.md#a-upstream) по группам проксируемых
HTTP-серверов в интерфейсе статистики, предоставляемом директивой
[api](https://angie.software//angie/docs/configuration/modules/http/http_api.md#a-api).
- [autoindex](https://angie.software//angie/docs/configuration/modules/http/http_autoindex.md#id3) выводит листинги директорий в естественном порядке.
- Вся функциональность [nginx 1.23.3](https://nginx.org/ru/CHANGES.ru).
#### Исправление
- Сборка завершалась ошибкой из-за ложного предупреждения компилятора при
использовании GCC 9 и старее с оптимизацией -O2 и выше.
#### Пакеты
15.03.2023
- Пакеты для операционных систем [Oracle](https://angie.software//angie/docs/installation/oss_packages.md#install-yum-oss) и
[Rocky](https://angie.software//angie/docs/installation/oss_packages.md#install-yum-oss) Linux.
- Пакеты динамических модулей:
- [angie-module-auth-spnego](https://github.com/stnoonan/spnego-http-auth-nginx-module)
- [angie-module-brotli](https://github.com/google/ngx_brotli)
- [angie-module-dav-ext](https://github.com/arut/nginx-dav-ext-module)
- [angie-module-headers-more](https://github.com/openresty/headers-more-nginx-module/)
- [angie-module-ndk](https://github.com/vision5/ngx_devel_kit)
- [angie-module-rtmp](https://github.com/arut/nginx-rtmp-module)
- [angie-module-set-misc](https://github.com/openresty/set-misc-nginx-module)
07.04.2023
- Пакеты для операционной системы [ALT](https://angie.software//angie/docs/installation/oss_packages.md#install-alt-oss) Linux.
11.05.2023
- Пакеты для операционной системы [FreeBSD](https://angie.software//angie/docs/installation/oss_packages.md#install-freebsd-oss).
- Пакеты динамических модулей:
- [angie-module-jwt](https://github.com/max-lt/nginx-jwt-module)
- [angie-module-subs](https://github.com/yaoweibin/ngx_http_substitutions_filter_module)
- [angie-module-upload](https://github.com/fdintino/nginx-upload-module)
- [angie-module-vod](https://github.com/kaltura/nginx-vod-module)
26.05.2023
- Пакеты для операционной системы [Astra](https://angie.software//angie/docs/installation/oss_packages.md#install-astrase-oss) Linux Special Edition.
---
## 2022
### Angie 1.0.0
Дата выпуска: 27.10.2022.
#### Добавления
- Директива [api](https://angie.software//angie/docs/configuration/modules/http/http_api.md#a-api), реализующая HTTP RESTful интерфейс для получения в
формате JSON базовой информации о веб-сервере, а также [статистики](https://angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) по клиентским соединениям, зонам разделяемой памяти, DNS-запросам,
HTTP-запросам, кэшу HTTP-ответов, сессиям модуля [stream](https://angie.software//angie/docs/configuration/modules/stream/index.md#stream-core)
и зонам модулей [limit_conn](https://angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#http-limit-conn)/[limit_req](https://angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req).
- Директива [status_zone](https://angie.software//angie/docs/configuration/modules/http/index.md#status-zone) в модуле [http](https://angie.software//angie/docs/configuration/modules/http/index.md#http-core)
для указания зоны сбора статистики по запросам в [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server) и
[location](https://angie.software//angie/docs/configuration/modules/http/index.md#location) контекстах.
- Директива [status_zone](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone) в модуле [stream](https://angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) для указания зоны сбора статистики по TCP/UDP сессиям.
- Параметр [status_zone](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver-status) директивы [resolver](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver) для
указания зоны сбора статистики по DNS-запросам.
- Переменная [$angie_version](https://angie.software//angie/docs/configuration/modules/http/index.md#v-angie-version), содержащая версию Angie.
- Вся функциональность [nginx 1.23.2](https://nginx.org/ru/CHANGES.ru).
# https://angie.software/angie/docs/pro_changes.md
# История версий Angie PRO
## 2026
### Angie PRO 1.11.8
Дата выпуска: 18.06.2026.
#### Безопасность
- При проксировании специально созданного запроса к gRPC-серверу с директивой
[ignore_invalid_headers](https://angie.software//angie/docs/configuration/modules/http/index.md#ignore-invalid-headers), установленной в `off`, и директивой
[large_client_header_buffers](https://angie.software//angie/docs/configuration/modules/http/index.md#large-client-header-buffers) с большим значением могло произойти
переполнение буфера, что позволяло атакующему испортить память рабочего
процесса или вызвать его падение
([CVE-2026-42055](https://nvd.nist.gov/vuln/detail/CVE-2026-42055));
исправление портировано из nginx 1.31.2.
- При обработке специально созданного ответа с декодированием из UTF-8 через
директиву [charset_map](https://angie.software//angie/docs/configuration/modules/http/http_charset.md#charset-map) могло происходить чтение данных за границами
буфера рабочего процесса, что позволяло атакующему отправить клиенту
ограниченное содержимое памяти рабочего процесса или вызвать его падение
([CVE-2026-48142](https://nvd.nist.gov/vuln/detail/CVE-2026-48142));
исправление портировано из nginx 1.31.2.
#### Исправления
- IP-адрес без номера порта в директивах [acme_http_port](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-http-port) или
[acme_dns_port](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-dns-port) вызывал падение главного процесса при чтении
конфигурации.
#### Пакеты
- Обновлены:
- [angie-pro-module-keyval](https://angie.software//angie/docs/installation/external-modules/keyval.md#external-keyval) — до версии 0.5.0
### Angie PRO 1.11.7
Дата выпуска: 15.06.2026.
#### Добавления
- Совместимость с OpenSSL 4.0.
#### Исправления
- В некоторых конфигурациях ответ на ACME DNS-проверку мог отправляться не
с того IP-адреса/интерфейса, на который был отправлен запрос, что могло
приводить к ошибке выпуска сертификата.
- При использовании [Docker-модуля](https://angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) быстрое завершение
контейнеров сразу после старта могло вызывать падение рабочего процесса.
- Изменение параметров в директивах [metric_zone](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-zone) или
[metric_complex_zone](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-complex-zone) для уже существующей зоны
могло привести к падению рабочего процесса при перезагрузке конфигурации.
- При использовании параметра `window=` метрики типа
`average mean` результат на некоторых периодах мог вычисляться
неправильно; в частности, вскоре после запуска системы на Linux значения
могли оставаться нулевыми.
- Значения метрик типов `count` и `histogram` неправильно
выводились на 32-битных платформах после достижения 2^32-1.
#### Пакеты
- Обновлены:
- [angie-pro-module-auth-jwt](https://angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) — до версии 0.14.1
- [angie-pro-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии v0.47.0
- [angie-pro-module-vod](https://angie.software//angie/docs/installation/external-modules/vod.md#external-vod) — до версии v1.8.1
### Angie PRO 1.11.6
Дата выпуска: 25.05.2026.
#### Безопасность
- При использовании директивы [rewrite](https://angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) с регулярным
выражением, содержащим вложенные захваты PCRE, и строкой замены,
ссылающейся на несколько таких захватов, атакующий при некоторых
независящих от него обстоятельствах мог вызвать падение рабочего
процесса, а на системах без рандомизации адресного пространства —
выполнение произвольного кода
([CVE-2026-9256](https://nvd.nist.gov/vuln/detail/CVE-2026-9256));
исправление портировано из nginx 1.31.1.
#### Пакеты
- Обновлены:
- [angie-pro-module-auth-jwt](https://angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) — до версии 0.13.1
- [angie-pro-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.9.9
- [angie-pro-module-testcookie](https://angie.software//angie/docs/installation/external-modules/testcookie.md#external-testcookie) — до версии 7d263d4
- [angie-pro-module-vod](https://angie.software//angie/docs/installation/external-modules/vod.md#external-vod) — до версии v1.7.2
### Angie PRO 1.11.5
Дата выпуска: 15.05.2026.
#### Безопасность
- При использовании директивы [rewrite](https://angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) с неименованным
захватом (например, `$1`, `$2`) и строкой замены, содержащей символ `?`,
за которой следует директива [rewrite](https://angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5), [if](https://angie.software//angie/docs/configuration/modules/http/http_rewrite.md#if) или [set](https://angie.software//angie/docs/configuration/modules/http/http_rewrite.md#set), атакующий при
некоторых независящих от него обстоятельствах мог вызвать падение
рабочего процесса, а на системах без рандомизации адресного
пространства — выполнение произвольного кода
([CVE-2026-42945](https://nvd.nist.gov/vuln/detail/CVE-2026-42945));
исправление портировано из nginx 1.31.0.
- При использовании директивы [ssl_ocsp](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ocsp) во время
обработки ответов DNS-сервера могло произойти обращение к ранее
освобождённой памяти, что позволяло атакующему повредить память
рабочего процесса или вызвать его падение
([CVE-2026-40701](https://nvd.nist.gov/vuln/detail/CVE-2026-40701));
исправление портировано из nginx 1.31.0.
- При использовании HTTP/3 атакующий мог выполнить
подмену IP-адреса и тем самым обойти ограничения или авторизацию в
некоторых конфигурациях
([CVE-2026-40460](https://nvd.nist.gov/vuln/detail/CVE-2026-40460));
исправление портировано из nginx 1.31.0.
- При использовании директив [scgi_pass](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass) или [uwsgi_pass](https://angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass)
атакующий, находясь в позиции посредника (MITM) и контролируя ответы
проксируемого сервера, мог вызвать избыточное выделение памяти или
чтение за пределами буфера, что позволяло отправить клиенту
содержимое памяти рабочего процесса или вызвать его падение
([CVE-2026-42946](https://nvd.nist.gov/vuln/detail/CVE-2026-42946));
исправление портировано из nginx 1.31.0.
- При обработке специально созданного ответа с
декодированием из UTF-8 через директиву [charset_map](https://angie.software//angie/docs/configuration/modules/http/http_charset.md#charset-map) могло
происходить чтение данных за границами буфера рабочего процесса, что
позволяло атакующему при некоторых независящих от него
обстоятельствах отправить клиенту ограниченное содержимое памяти
рабочего процесса или вызвать его падение
([CVE-2026-42934](https://nvd.nist.gov/vuln/detail/CVE-2026-42934));
исправление портировано из nginx 1.31.0.
#### Пакеты
- Обновлены:
- [angie-pro-module-auth-totp](https://angie.software//angie/docs/installation/external-modules/auth-totp.md#external-auth-totp) — до версии 1.2.0
- [angie-pro-module-cache-purge](https://angie.software//angie/docs/installation/external-modules/cache-purge.md#external-cache-purge) — до версии 3.0.2
- [angie-pro-module-keyval](https://angie.software//angie/docs/installation/external-modules/keyval.md#external-keyval) — до версии 0.4.0
- [angie-pro-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.9.8
- [angie-pro-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии v0.46.0
- Изменён источник [angie-pro-module-dav-ext](https://angie.software//angie/docs/installation/external-modules/dav-ext.md#external-dav-ext) на
[mid1221213/nginx-dav-ext-module](https://github.com/mid1221213/nginx-dav-ext-module) v4.0.1.
- Изменён источник [angie-pro-module-vod](https://angie.software//angie/docs/installation/external-modules/vod.md#external-vod) на
[dio-az/nginx-vod-module](https://github.com/dio-az/nginx-vod-module) v1.7.1.
### Angie PRO 1.11.4
Дата выпуска: 25.03.2026.
#### Безопасность
- TLS-согласование с клиентом в [stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream)-модуле могло
завершиться успешно при том, что OCSP отклонил клиентский сертификат
([CVE-2026-28755](https://nvd.nist.gov/vuln/detail/CVE-2026-28755));
исправление портировано из nginx 1.29.7.
- В DAV-модуле при обработке COPY- или MOVE-запроса в
`location` с директивой [alias](https://angie.software//angie/docs/configuration/modules/http/index.md#alias) могло произойти переполнение буфера,
что позволяло атакующему модифицировать исходный или целевой путь за
пределы корневой директории
([CVE-2026-27654](https://nvd.nist.gov/vuln/detail/CVE-2026-27654));
исправление портировано из nginx 1.29.7.
- Обработка специально созданного файла в MP4-модуле на
32-битных платформах могла приводить к падению рабочего процесса, а
также потенциально могла иметь другие последствия
([CVE-2026-27784](https://nvd.nist.gov/vuln/detail/CVE-2026-27784));
исправление портировано из nginx 1.29.7.
- Обработка специально созданного файла MP4-модулем могла
приводить к падению рабочего процесса, а также потенциально могла
иметь другие последствия
([CVE-2026-32647](https://nvd.nist.gov/vuln/detail/CVE-2026-32647));
исправление портировано из nginx 1.29.7.
- Если в почтовом прокси-модуле ([Mail](https://angie.software//angie/docs/configuration/modules/index.md#modules-mail)) использовался метод
аутентификации CRAM-MD5 или APOP и были разрешены повторные попытки
аутентификации, то могло произойти падение рабочего процесса
([CVE-2026-27651](https://nvd.nist.gov/vuln/detail/CVE-2026-27651));
исправление портировано из nginx 1.29.7.
- Когда использовался почтовый прокси-модуль ([Mail](https://angie.software//angie/docs/configuration/modules/index.md#modules-mail)), атакующий с
помощью PTR DNS-записи мог вставить данные в HTTP-запросы
аутентификации, а также в команду XCLIENT в SMTP-соединении к
проксируемому серверу
([CVE-2026-28753](https://nvd.nist.gov/vuln/detail/CVE-2026-28753));
исправление портировано из nginx 1.29.7.
#### Исправления
- Редкие системные ошибки перед подключением к
проксируемому серверу могли повлиять на корректность статуса
проксируемых серверов в модулях [HTTP](https://angie.software//angie/docs/configuration/modules/index.md#modules-http) и
[stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream); в [stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream)-модуле они
также могли привести к падению рабочего процесса; проблема появилась
в 1.9.1.
- В конфигурациях, где директивы [proxy_http_version](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version) `3` и
[proxy_set_header](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-set-header) `Host ..` наследовались из блока `http`,
исходящие HTTP/3-запросы могли отправляться без заголовка `Host`.
#### Пакеты
- Обновлены:
- [angie-pro-module-auth-jwt](https://angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) — до версии 0.11.0
- [angie-pro-module-cache-purge](https://angie.software//angie/docs/installation/external-modules/cache-purge.md#external-cache-purge) — до версии 2.5.6
- [angie-pro-module-cgi](https://angie.software//angie/docs/installation/external-modules/cgi.md#external-cgi) — до версии v0.15
- [angie-pro-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.9.6
- [angie-pro-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии v0.43.0
### Angie PRO 1.11.3
Дата выпуска: 06.02.2026.
#### Безопасность
- Атакующий, находясь в позиции посредника (MITM) перед проксируемым сервером
с использованием TLS, при некоторых независящих от него обстоятельствах мог
внедрить в ответ данные в виде открытого текста до начала TLS-согласования
([CVE-2026-1642](https://nvd.nist.gov/vuln/detail/CVE-2026-1642));
исправление портировано из nginx 1.29.5.
#### Пакеты
- Обновлены:
- [angie-pro-module-jwt](https://angie.software//angie/docs/installation/external-modules/jwt.md#external-jwt) — до версии 3.4.4
### Angie PRO 1.11.2
Дата выпуска: 15.01.2026.
#### Исправления
- Если BPF был отключен, то HTTP/3-запросы могли
завершаться с ошибкой `[alert] sendmsg() failed (90: Message too
large) while sending frames`;
проблема появилась в 1.11.0.
- HTTP/3-запросы не принимались при прослушивании wildcard
IPv6-адреса и включённом BPF;
проблема появилась в 1.11.0.
- При указании доменного имени в директиве [docker_endpoint](https://angie.software//angie/docs/configuration/modules/http/http_docker.md#docker-endpoint)
подключения к Docker API и обновления групп
проксируемых серверов не происходили.
#### Пакеты
- Обновлены:
- [angie-pro-module-cache-purge](https://angie.software//angie/docs/installation/external-modules/cache-purge.md#external-cache-purge) — до версии 2.5.5
02.02.2026
- Обновлены:
- [angie-pro-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.9.5
## 2025
### Angie PRO 1.11.1
Дата выпуска: 30.12.2025.
#### Изменения
- Теперь, если в директиве [acme_http_port](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-http-port) указан
только порт без IP (значение по умолчанию) и есть слушающие на этом
порту блоки `server`, то обработка HTTP-подверждений для
заданного порта в ACME работает только на указанных IP-адресах в
директивах [listen](https://angie.software//angie/docs/configuration/modules/http/index.md#listen) данных блоков; попытки слушать на всех остальных IP,
как было раньше, не производится; это делает настройку более гибкой и
предотвращает возможную проблему при обновлении с предыдущих версий на
конфигурациях, где были только блоки `server`, слушающие на
`80` порту и конкретных IP-адресах.
#### Исправления
- HTTP/2-запросы не учитывались в серверных зонах
статистики; проблема появилась в 1.11.0.
- Если ACME-клиент был отключен в конфигурации и не имел
ранее полученного сертификата, запрос к API статистики для данного
клиента мог привести к падению рабочего процесса.
- Если в качестве ключа директивы [status_zone](https://angie.software//angie/docs/configuration/modules/http/index.md#status-zone), заданной на уровне
блоков `server`, использовались переменные `$http_host` или
`$cookie_*`, то HTTP/3-запросы могли не учитываться в указанной
зоне статистики.
#### Пакеты
- Обновлены:
- [angie-pro-module-vts](https://angie.software//angie/docs/installation/external-modules/vts.md#external-vts) — до версии v0.2.5
### Angie PRO 1.11.0
Дата выпуска: 24.12.2025.
#### Изменения
- Переменная `$http_host` в запросах по протоколу HTTP/3
теперь инициализируется из значения псевдозаголовка `:authority`,
если заголовок `Host` не был передан, что является нормальным для
клиентов; до этого отличия в поведении от протоколов младших версий
могли создавать проблемы в конфигурациях с использованием переменной
`$http_host`.
- Если все HTTP-сервера в `upstream`-группе оказываются
недоступны или возвращают ошибку, то теперь всегда возвращается
собственная страница ошибки вместо принятой от последнего сервера,
когда тот вернул ошибочный статус согласно настройкам директивы
[proxy_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream) (и ей подобных); это позволяет получить
консистентное поведение во всех случаях.
- Параметр `REQUEST_METHOD` в файлах конфигурации
`fastcgi.conf`, `fastcgi_params`, `uwsgi_params` и `scgi_params`
теперь устанавливается через переменную `$upstream_request_method`,
которая принимает значение `GET` для `HEAD`-запросов при настройке
кэширования; это предотвращает проблему, когда ранее в результате
`HEAD`-запроса могло происходить сохранение пустых ответов, которые
затем отдавались на `GET`-запросы, так как в типичной конфигурации
метод запроса не является ключом кэширования.
- Максимальный размер ответа от ACME-сервера теперь
ограничивается директивой [acme_max_response_size](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-max-response-size), а не
параметром `max_cert_size=` директивы [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client); заданного по
умолчанию значения достаточно для большинства случаев, но в случае,
если обновление завершается ошибкой `[error] too big subrequest
response while sending to client`, его следует увеличить.
- Значение по умолчанию директивы [variables_hash_max_size](https://angie.software//angie/docs/configuration/modules/http/index.md#variables-hash-max-size)
в HTTP-модуле увеличено до `2048`, чтобы снизить вероятность появления
предупреждений о неоптимальном построении хэша из-за добавления
множества новых переменных за последние годы: `[warn] could not build
optimal variables_hash, you should increase either
variables_hash_max_size: 1024 or variables_hash_bucket_size: 64;
ignoring variables_hash_bucket_size`.
#### Добавления
- Произвольно конфигурируемый сбор статистики с помощью
нового модуля [Metric](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#http-metric) в HTTP; позволяет, используя различные методы
(счетчики, гистограммы, скользящие средние и др.), агрегировать любые
данные на разных стадиях обработки запроса в реальном времени с
помощью переменных по заданным ключам и отдавать их в секции
`/status/http/metric_zones/` API статистики (с поддержкой
Prometheus), тем самым добавляя встроенный мощный аналитический
инструмент для всего HTTP-трафика.
- Поддержка ALPN-верификации для ACME, задаваемая при
помощи значения `alpn` в качестве параметра `challenge` директивы
[acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client); позволяет запрашивать мультидоменные сертификаты,
держа открытым только HTTPS-порт.
- Информация об ACME-клиентах и процедуре получения
сертификата в разделе `/status/http/acme_clients/` API статистики (с
поддержкой Prometheus).
- Добавлена поддержка Encrypted Client Hello (ECH) в HTTP и
stream SSL-модулях; директива [ssl_encrypted_hello_key](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-encrypted-hello-key) позволяет
задать файл с приватным ключом; переменная `$ssl_encrypted_hello`
содержит информацию об использовании ECH.
Спасибо Максиму Дунину (freenginx).
- Конвертация формата изображения с помощью параметра
`convert` директивы [image_filter](https://angie.software//angie/docs/configuration/modules/http/http_image_filter.md#id3).
- Поддержка форматов AVIF и HEIC в модуле Image Filter.
- Поддержка PROXY-протокола второй версии в stream-модуле в
сторону проксируемых серверов с возможностью передачи произвольных
значений через TLV-записи с помощью директивы
[proxy_protocol_tlv](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-protocol-tlv), в которой можно указывать строки с переменными.
- Переменная `$upstream_request_method`, содержащая метод
запроса к проксируемому серверу, который может отличаться от метода
запроса клиента при использовании кэширования или директивы
[proxy_method](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-method); позволяет легко избежать распространенной проблемы в
конфигурациях, когда на `GET`-запрос возвращается закэшированный пустой
`HEAD`-ответ, а также избежать кэширования `HEAD` и `GET` отдельно.
- Режим работы [sticky](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky), при котором сессии хранятся только
на удалённом сервере и всегда запрашиваются с него, теперь доступен
также и в `stream`-модуле; ранее он был доступен только в HTTP.
- В режиме хранения привязки [sticky](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky)-сессий во внешнем
хранилище теперь обрабатывается тело ответа; это позволяет извлекать
данные о сессии из тела ответа на запрос к внешнему хранилищу, а не
только из полей заголовка.
- Теперь HTTP-верификация в ACME может работать без блоков
`server` с директивой `listen 80` в конфигурации; при необходимости
слушающий порт можно изменить с помощью новой директивы
[acme_http_port](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-http-port).
- Возможность подсчета количества элементов в списках и
объектах при экспорте метрик Prometheus; пути, оканчивающиеся косой
чертой, теперь возвращают количество элементов в соответствующей
коллекции API.
- Переменная `$sent_body`, содержащая тело ответа
подзапроса или запроса от клиентского модуля.
- Поддержка методов аутентификации XOAUTH2 и OAUTHBEARER в
почтовом прокси-сервере.
Спасибо Rob Mueller и Максиму Дунину (freenginx).
- Параметр `route` директивы [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) теперь может
содержать произвольные строки с любым количеством переменных.
- В модуле ACME автоматически вычисляется приблизительный
размер получаемого сертификата, что устраняет необходимость
увеличивать параметр `max_cert_size` директивы [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) в
случаях выпуска сертификата с очень большим количеством доменов;
параметр оставлен для случаев, когда ручная настройка всё же
понадобится.
- Информация о лицензии и ограничениях в API-секции
`/status/angie/license`.
- Переменная `$upstream_cache_key`, содержащая используемый
ключ кэширования.
Спасибо Кириллу Коринскому и Максиму Дунину (freenginx).
- Вся функциональность nginx 1.29.3, за исключением
директив `add_header_inherit` и `add_trailer_inherit`, качество
проработки которых крайне низкое.
#### Исправления
- Процедуры перезагрузки конфигурации и обновления
исполняемого файла на лету теперь работают штатно с
HTTP/3-соединениями; реализован корректный роутинг соединений ко всем
существующим процессам при помощи модуля BPF.
- Если все сервера в `upstream`-группе оказывались
недоступны или возвращали ошибку, то ошибочный ответ последнего мог
посчитаться успешным несмотря на настройки директивы
[proxy_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream).
- Когда путь в директиве [try_files](https://angie.software//angie/docs/configuration/modules/http/index.md#try-files) был короче, чем префикс в
соответствующем блоке `location`, использование
[proxy_pass](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) с URI могло приводить к падению рабочего процесса;
исправление портировано из nginx 1.29.4.
- Если в блоке `stream` не было ссылающихся на ACME-клиент
директив `acme`, то при указании в нём соответствующих переменных
`$acme_cert_*` конфигурация не принималась с ошибкой
`unknown variable`; проблема появилась в 1.10.3.
- Если было настроено сохранение индекса кэша в файл,
тестирование конфигурации во время работы могло завершаться ошибками
типа `[alert] mmap() failed (17: File exists)` и
`[alert] munmap() failed (22: Invalid argument)`.
- Директива [proxy_method](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-method) игнорировалась при срабатывании
директивы `proxy_cache_convert_head on`.
- Длительность тайм-аута, задаваемого опцией
`fail_timeout` директивы `server` блока `upstream`, была на 1 секунду
больше, чем указано.
- Загрузка модулей, собранных для версии Angie с открытым
исходным кодом, могла приводить к некорректной работе и падениям
из-за несовместимости ABI; теперь подобные ошибочные конфигурации
запрещены, и выдается соответствующее сообщение об ошибке.
#### Пакеты
- Обновлены:
- [angie-pro-module-echo](https://angie.software//angie/docs/installation/external-modules/echo.md#external-echo) — до версии v0.64
### Angie PRO 1.10.3
Дата выпуска: 13.11.2025.
#### Безопасность
- Обработка специально созданного логина/пароля при
использовании метода аутентификации `none` в SMTP-модуле могла
приводить к отправке серверу аутентификации части содержимого памяти
рабочего процесса ([CVE-2025-53859](https://nvd.nist.gov/vuln/detail/CVE-2025-53859)); исправление портировано из nginx
1.29.1.
#### Исправления
- Если при использовании опции `renew_on_load` директивы
[acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) присутствовал ранее полученный сертификат, то он не
загружался, что могло ограничивать работоспособность до окончания
обновления сертификата; если сертификат отсутствовал, то попытки
получения нового завершались ошибкой `[alert] lseek() failed (9: Bad
file descriptor)`.
- Если [ACME-клиент](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#id4) использовался в блоке `stream`, но не в
блоке `http`, он деактивировался с предупреждением `[warn] ACME
client .. is defined but not used` и не получал сертификата.
- Если все директивы [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) содержали параметр
`enabled=off` и соответствующие переменные `$acme_cert_*`
использовались в конфигурации, то Angie не запускался, сообщая об
ошибке `[emerg] unknown acme_cert_* variable`.
- Если [ACME-клиент](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#id4) использовался в блоке `stream`, который
располагался перед блоком `http`, то Angie не запускался, сообщая об
ошибке `[emerg] ACME client .. is not defined but referenced`.
- Некоторые конфигурации блока `client` могли вызывать
падение рабочих процессов при использовании переменных, связанных с
отсутствующим в данном случае входящим соединением.
- Сервера, добавленные [Docker-модулем](https://angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) в upstream-группы,
не проверялись активными проверками.
- Параметр `send=` директивы [upstream_probe (PRO)](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe) в
stream-модуле работал некорректно для UDP-проверок при указании пути
к файлу: вместо содержимого файла отправлялся сам путь.
- Если использовалась опция `learn` директивы [sticky](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky), то
после перезагрузки конфигурации параметр `timeout=` мог не работать
до тех пор, пока не появлялась хотя бы одна новая сессия.
#### Пакеты
- Обновлены:
- [angie-pro-module-cache-purge](https://angie.software//angie/docs/installation/external-modules/cache-purge.md#external-cache-purge) — до версии 2.5.4
- [angie-pro-module-cgi](https://angie.software//angie/docs/installation/external-modules/cgi.md#external-cgi) — до версии v0.14.1
- [angie-pro-module-lua](https://angie.software//angie/docs/installation/external-modules/lua.md#external-lua) — до версии 0.10.29
- [angie-pro-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.9.4
---
### Angie PRO 1.10.2
Дата выпуска: 21.08.2025.
#### Исправления
- Настройки прокси-модуля в блоке `http` могли нарушать
работу модулей, которые используют блок `client` для исходящих
запросов; проблема появилась в 1.10.0.
- Включение [proxy_ignore_client_abort](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ignore-client-abort) совместно с
модулями, использующими блок `client` для исходящих запросов, могло
приводить к падению рабочих процессов; проблема появилась в 1.10.0.
- Если в группе проксируемых серверов был ранее
сконфигурирован один сервер, то серверы, добавленные через [Docker
API](https://angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker), могли не участвовать в балансировке.
- Если единственный сервер в группе проксируемых серверов
был добавлен посредством [Docker API](https://angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker), то в случае признания его
недоступным он мог исключаться из балансировки.
#### Пакеты
- Добавлены динамические модули:
- [angie-pro-module-auth-totp](https://angie.software//angie/docs/installation/external-modules/auth-totp.md#external-auth-totp)
- [angie-pro-module-combined-upstreams](https://angie.software//angie/docs/installation/external-modules/combined-upstreams.md#external-combined-upstreams)
- Обновлены:
- [angie-pro-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии 0.41.0
---
### Angie PRO 1.10.1
Дата выпуска: 17.07.2025.
#### Изменения
- Директивы, заданные на уровне блока `client`, теперь могут наследоваться
только в явно объявленных внутри него блоках `location` и не оказывают
влияния на настройки других модулей, неявно использующих блок `client`
для исходящих запросов.
#### Добавления
- Поддержка нескольких блоков `client` позволяет сгруппировать общие
настройки для разных блоков `location` внутри каждого из них, что
помогает избежать дублирования конфигурации.
#### Исправления
- Параметр `reuseport` в директиве `listen` приводил к тому, что все
соединения на указанный адрес и порт обслуживались только одним рабочим
процессом; проблема появилась в версии 1.10.0.
- Обращение к специальным переменным `$stream_*` вне контекста обработки
запроса sticky-сессии модуля `stream` приводило к падению рабочего
процесса.
- HTTP/3-согласование с проксируемым сервером могло завершаться ошибкой при
использовании библиотеки OpenSSL версии 3.5.0 или выше, если на сервере был
активен режим `retry` QUIC-протокола.
---
### Angie PRO 1.10.0
Дата выпуска: 03.07.2025.
#### Добавления
- Автоматическое получение и динамическое обновление групп проксируемых серверов
на основе меток Docker-контейнеров (или Podman), настраиваемое с помощью
директивы [docker_endpoint](https://angie.software//angie/docs/configuration/modules/http/http_docker.md#docker-endpoint); это позволяет на указанном Docker API в
реальном времени отслеживать запуск и остановку контейнеров и, соответственно,
добавлять или удалять их адреса из списка `upstream` согласно прописанным
в них специальным меткам и без перезагрузки конфигурации.
- Поддержка автоматического получения TLS-сертификатов по протоколу ACME в
`stream`-модуле, настраиваемое с использованием директивы [acme](https://angie.software//angie/docs/configuration/modules/stream/stream_acme.md#s-acme)
и переменных вида [$acme_cert_\*](https://angie.software//angie/docs/configuration/modules/stream/stream_acme.md#v-s-acme-cert-name) и
[$acme_cert_key_\*](https://angie.software//angie/docs/configuration/modules/stream/stream_acme.md#v-s-acme-cert-key-name).
- Привязка `stream`-сессий для группы проксируемых серверов с HTTP-запросом
во внешнее хранилище, настраиваемое директивой [sticky](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky) в режиме
`learn` с помощью параметров `remote_action`, `remote_result`
и `remote_uri`; это позволяет привязывать клиентские сессии к
балансируемым серверам в кластерном режиме, когда группа балансировщиков
объединяется общим хранилищем и направляет запросы клиента в рамках одной
сессии на один и тот же сервер вне зависимости от того, на какой балансировщик
они попали.
- Новый параметр `norefresh` директивы `sticky` (в режиме `learn`),
позволяющий отключать автоматическое продление жизни сессий при их использовании.
- Новый режим работы [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) с сессиями, при котором сессии хранятся только
на удаленном сервере и всегда запрашиваются с него; кэширование ответов
удаленного сервера при этом может быть гибко настроено в модуле проксирования.
- Возможность группе резервных (backup) проксируемых `stream`-серверов
оставаться активной в случае, когда серверы из основной группы стали вновь
доступны, использующая директиву `backup_switch permanent[=timeout]` в
блоке [upstream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream).
- Поддержка приема соединений по протоколу MPTCP, включаемая с помощью опции
`multipath` директивы [listen](https://angie.software//angie/docs/configuration/modules/http/index.md#listen).
Спасибо Максиму Дунину (freenginx), Максиму Дурову и Энтони Дорену.
- Блок [client](https://angie.software//angie/docs/configuration/modules/http/index.md#client), позволяющий задавать дополнительную конфигурацию для
внутренних HTTP-запросов, исходящих от различных модулей.
- Вся функциональность [nginx 1.27.5](https://nginx.org/ru/CHANGES.ru),
включая контроль перегрузки CUBIC в соединениях QUIC.
#### Исправления
- У проксируемых серверов в режиме `drain` не останавливался отсчет
времени неработоспособности в API статистики после того, как проксируемый
сервер снова становился доступным по результатам пассивных проверок.
#### Пакеты
- Обновлены:
- [angie-pro-console-light](https://angie.software//angie/docs/installation/pro_packages.md#install-console-light-pro) — до версии 1.8.0
- [angie-pro-module-cgi](https://angie.software//angie/docs/installation/external-modules/cgi.md#external-cgi) — до версии 0.13
- [angie-pro-module-otel](https://angie.software//angie/docs/installation/external-modules/otel.md#external-otel) — до версии 0.1.2
14.07.2025
- Обновлены:
- [angie-pro-module-headers-more](https://angie.software//angie/docs/installation/external-modules/headers-more.md#external-headers-more) — до версии v0.39
- [angie-pro-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs),
[angie-pro-module-njs-light](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.9.1
---
### Angie PRO 1.9.1
Дата выпуска: 29.05.2025.
#### Добавления
- Возможность задать в директиве [acme_dns_port](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-dns-port) не только номер порта, но
и IP-адрес; поддерживаются IPv4 и IPv6.
#### Исправления
- Одновременное наличие в директивах [server_name](https://angie.software//angie/docs/configuration/modules/http/index.md#server-name) wildcard-домена и
совпадающих с ним доменов третьего уровня приводило к ошибке ACME-сервера при
выпуске сертификата для этих доменов в рамках одного ACME-клиента.
- В `stream`-модуле после успешного соединения с проксируемым сервером во
время пассивной проверки его статус в API статистики ошибочно продолжал
отображаться как `unavailable` до завершения сессии.
- В `stream`-модуле отсчет времени неработоспособности в API статистики
мог остановиться или ошибочно сброситься, если проксируемый сервер находился в
состоянии `unhealthy`.
- Запросы HTTP/3 могли зависать и завершаться по таймауту; исправление
портировано из nginx 1.29.0.
- Ранняя ошибка при установлении соединения HTTP/3 с проксируемым сервером могла
приводить к падению рабочего процесса.
- При проксировании по протоколу HTTP/3 число активных соединений
могло отображаться в статистике некорректно.
- Когда проксируемый сервер в режиме `drain` оказывался недоступен,
попытка соединиться с другим сервером согласно настройкам
[proxy_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream) и аналогичным директивам могла не выполняться.
#### Пакеты
- Добавлены динамические модули:
- - [angie-pro-module-njs-light](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs)
- Обновлены:
- [angie-pro-module-auth-spnego](https://angie.software//angie/docs/installation/external-modules/auth-spnego.md#external-auth-spnego) — до версии 1.1.3
- [angie-pro-module-cgi](https://angie.software//angie/docs/installation/external-modules/cgi.md#external-cgi) — до версии 0.12.1
- [angie-pro-module-modsecurity](https://angie.software//angie/docs/installation/external-modules/modsecurity.md#external-modsec) — до версии 1.0.4
- [angie-pro-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.9.0
- [angie-pro-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии 0.40.0
---
### Angie PRO 1.9.0
Дата выпуска: 11.04.2025.
#### Добавления
- Возможность задать файл в директиве [proxy_cache_path](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path), в который между
запусками сервера будет сохраняться содержимое зоны разделяемой памяти с
индексом кэша; что избавляет от необходимости подгружать кэш после
перезагрузки и позволяет практически сразу вернуть сервер в работу.
- Возможность группе резервных (backup) проксируемых HTTP-серверов оставаться
активной в случае, когда серверы из основной группы стали вновь доступны,
использующая директиву [backup_switch permanent[=timeout]](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-backup-switch)
в блоке `upstream`.
- Поддержка механизма TLS 1.3 Early Data (0-RTT) в `stream`-модуле с
помощью директивы [ssl_early_data](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#s-ssl-early-data).
- Новый статус `busy` у проксируемых серверов в API статистики, означающий,
что число запросов на сервер достигло ограничения, заданного опцией
`max_conns`.
- Параметр `uri=` в директиве [acme_hook](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook), который позволяет
переопределять строку запроса к внешнему приложению, в том числе, используя
переменные.
- Параметр `renew_on_load` директивы [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client), позволяющий
форсировать обновление сертификата при загрузке конфигурации.
- Отображение даты и времени сборки в поле `build_time` объекта
`/status/angie` API статистики, а также в выводе ключа командной строки
`-V`.
- Вся функциональность [nginx 1.27.4](https://nginx.org/ru/CHANGES.ru), за
исключением директивы `keepalive_min_timeout` (аналогичный функционал
существует с версии 1.8.0).
#### Изменения
- Параметр `enabled=off` в директиве [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) теперь отключает
только обновление сертификата для данного клиента, но сохраняет весь остальной
функционал; так, остается возможность использовать ключ и сертификат (при
наличии) через переменные `$acme_cert_*`, а использование переменных
`$acme_hook_*` и директив `acme` не приводит к ошибкам.
- Ошибка `no valid domain name defined for ACME client` теперь возникает
только если на ACME-клиент есть ссылка из директивы `acme` в блоке
`server`, но ни один из доменов этого сервера не соответствует требованиям
ACME.
#### Исправления
- При сборке с поддержкой NTLS наследование директив
`proxy_ssl_certificate` и `proxy_ssl_certificate_key` с
переменными работало некорректно.
#### Пакеты
- Обновлены:
- [angie-pro-module-cgi](https://angie.software//angie/docs/installation/external-modules/cgi.md#external-cgi) — до версии 0.11.1
- [angie-pro-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.8.10
---
### Angie PRO 1.8.3
Дата выпуска: 02.04.2025.
#### Исправления
- Cтатистика [status_zone](https://angie.software//angie/docs/configuration/modules/http/index.md#status-zone) в блоке [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server) HTTP-модуля могла
считаться некорректно, если запросы попадали в разные зоны статистики в рамках
одного соединения или на раннем этапе обработки запроса происходила ошибка;
проблема появилась в 1.8.2.
#### Пакеты
- Обновлены:
- [angie-pro-console-light](https://angie.software//angie/docs/installation/pro_packages.md#install-console-light-pro) — до версии 1.7.0
- [angie-pro-module-cgi](https://angie.software//angie/docs/installation/external-modules/cgi.md#external-cgi) — до версии 57f660bb2c6ef6e4b75c65406080d0236860ca08
- [angie-pro-module-jwt](https://angie.software//angie/docs/installation/external-modules/jwt.md#external-jwt) — до версии v3.4.3
- [angie-pro-module-ndk](https://angie.software//angie/docs/installation/external-modules/ndk.md#external-ndk) — до версии v0.3.4
- [angie-pro-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии v0.39.0
- [angie-pro-module-vts](https://angie.software//angie/docs/installation/external-modules/vts.md#external-vts) — до версии v0.2.4
04.04.2025
- Обновлены:
- [angie-pro-console-light](https://angie.software//angie/docs/installation/pro_packages.md#install-console-light-pro) — до версии 1.7.1
07.04.2025
- Обновлены:
- [angie-pro-console-light](https://angie.software//angie/docs/installation/pro_packages.md#install-console-light-pro) — до версии 1.7.2
### Angie PRO 1.8.2
Дата выпуска: 13.02.2025.
#### Безопасность
- Недостаточная проверка в обработке виртуальных серверов при использовании SNI
в TLSv1.3 позволяла повторно использовать SSL-сессию в контексте другого
виртуального сервера, обходя проверку клиентских SSL-сертификатов
([CVE-2025-23419](https://www.cve.org/CVERecord?id=CVE-2025-23419));
исправление портировано из nginx 1.27.4.
#### Исправления
- Активные проверки, заданные директивой [upstream_probe (PRO)](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe) в
`stream`-модуле, могли приводить к падению рабочего процесса.
- Запросы к API для получения значений статистики из отдельной зоны, которая
была задана через переменные, могли приводить к зацикливанию рабочего
процесса.
- HTTP/3-запросы не учитывались в зонах статистики; проблема появилась в 1.8.0.
- TLS-согласования по протоколу QUIC не учитывались в статистике по SSL.
- Использование доменных имен, начинающихся с точки, в директиве
[server_name](https://angie.software//angie/docs/configuration/modules/http/index.md#server-name), могло привести к ошибке обновления сертификата по
[протоколу ACME](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#id4).
#### Пакеты
- Добавлены динамические модули:
- [angie-pro-module-auth-pam](https://github.com/sto/ngx_http_auth_pam_module)
- [angie-pro-module-cgi](https://github.com/pjincz/nginx-cgi)
---
## 2024
### Angie PRO 1.8.1
Дата выпуска: 28.12.2024.
#### Исправления
- Использование директивы [status_zone](https://angie.software//angie/docs/configuration/modules/http/index.md#status-zone) в блоке `server` HTTP-модуля
приводило к избыточному логированию пустых запросов в [access_log](https://angie.software//angie/docs/configuration/modules/http/http_log.md#access-log) во
время TLS-согласований; проблема появилась в 1.8.0.
- Ошибки декодирования потока HTTP/3 могли приводить к падению рабочего процесса
при закрытии QUIC-соединения; исправление портировано из nginx 1.27.4.
- Отправка пакетов с согласованием версии протокола QUIC могла привести к
бесконечному циклу обмена пакетами; исправление портировано из nginx 1.27.4.
- Использование DNS-валидации без хуков в [ACME-модуле](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) на
некоторых конфигурациях могло привести к падению рабочего процесса.
#### Пакеты
- Обновлены:
- [angie-pro-module-auth-jwt](https://angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) — до версии 0.9.0
23.01.2025
- Обновлены:
- [angie-pro-console-light](https://angie.software//angie/docs/installation/pro_packages.md#install-console-light-pro) — до версии 1.6.0
27.01.2025
- Добавлены динамические модули:
- [angie-pro-module-unbrotli](https://github.com/clyfish/ngx_unbrotli)
- Обновлены:
- [angie-pro-console-light](https://angie.software//angie/docs/installation/pro_packages.md#install-console-light-pro) — до версии 1.6.1
- [angie-pro-module-auth-spnego](https://angie.software//angie/docs/installation/external-modules/auth-spnego.md#external-auth-spnego) — до версии v1.1.2
- [angie-pro-module-headers-more](https://angie.software//angie/docs/installation/external-modules/headers-more.md#external-headers-more) — до версии v0.38
- [angie-pro-module-lua](https://angie.software//angie/docs/installation/external-modules/lua.md#external-lua) — до версии 0.10.28
- [angie-pro-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.8.9
- [angie-pro-module-vts](https://angie.software//angie/docs/installation/external-modules/vts.md#external-vts) — до версии v0.2.3
- [angie-pro-module-wasm](https://angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-core) — до версии v0.2-beta2
---
### Angie PRO 1.8.0
Дата выпуска: 19.12.2024.
#### Добавления
- Привязка HTTP-сессий для группы проксируемых серверов с запросом во внешнее
хранилище, настраиваемое директивой [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) в режиме `learn` с
помощью параметров `remote_action` и `remote_result`. Это
позволяет конфигурировать привязку клиентских сессий к балансируемым серверам
в кластерном режиме, когда группа балансировщиков объединяется общим
хранилищем и направляет запросы клиента в рамках одной сессии на один и тот же
сервер вне зависимости от того, на какой балансировщик они попали.
- Поддержка валидации `DNS-01` посредством ответа на DNS-запрос от
ACME-сервера, что позволяет автоматически запрашивать сертификаты любых типов,
в том числе wildcard.
- Система внешних вызовов в модуле ACME, настраиваемая с помощью директивы
[acme_hook](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook), которая позволяет обеспечить валидацию доменных имен
посредством внешнего обработчика для интеграции с различными сервисами и
провайдерами DNS-хостинга.
- ACME-модуль выводит в лог дополнительную информацию: точная причина обновления
сертификата, полный список доменов, идентификатор аккаунта пользователя,
длительные периоды неактивности (например, во время опросов), какой домен
выполняет валидацию. Такая информация позволяет легче диагностировать проблемы
на этапе перевыпуска сертификатов, а также прописывать DNS-запись CAA.
- Параметр `account_key` в директиве [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client), позволяющий
переиспользовать существующий ключ аккаунта ACME-сервера, а не генерировать
новый автоматически.
- Поддержка переменных в директиве [status_zone](https://angie.software//angie/docs/configuration/modules/http/index.md#status-zone) в модулях HTTP и stream
позволяет динамически распределять статистику по нескольким зонам в рамках
одного блока `location` или `server`. Это, в частности, пригодится
для случая, когда один блок `server` обрабатывает несколько виртуальных
хостов.
- Совместимость HTTP-модуля сжатия GZip с версиями библиотеки `zlib-ng`
2.2.0 и выше, которые ранее могли приводить к появлению в логе ошибок вида
`[alert] gzip filter failed to use preallocated memory`.
- Директива [max_headers](https://angie.software//angie/docs/configuration/modules/http/index.md#max-headers), ограничивающая максимальное количество полей
заголовка в HTTP-запросе для лучшей защиты от DoS-атак. Спасибо Максиму Дунину
(freenginx) и Максиму Евменкину.
- Директивы [http3_max_table_capacity](https://angie.software//angie/docs/configuration/modules/http/http_v3.md#http3-max-table-capacity) и
[proxy_http3_max_table_capacity](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-max-table-capacity) для настройки ограничения на размер
динамической таблицы сжатия заголовка в HTTP/3.
- Поддержка кросс-компиляции — система сборки теперь может использовать
скрипт-обертку для запуска автотестов, что позволяет подготовить сборку без
запуска тестовых программ непосредственно на целевой платформе.
- Вся функциональность [nginx 1.27.3](https://nginx.org/ru/CHANGES.ru).
#### Исправления
- HTTP/3-клиенты могли отключаться по таймауту при использовании `0-RTT`.
Проблема была унаследована из nginx в версии 1.7.0.
- Проксирование по HTTP/3 с использованием переменных в директиве
[proxy_pass](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) и без указания блока `upstream` могло приводить к
падению рабочего процесса.
- Кэширование HTTP/3-ответов при использовании динамической таблицы сжатия
заголовка могло привести к падению рабочего процесса.
- Некоторые SSL-рукопожатия могли не учитываться в счетчиках статистики для
stream-модуля.
- Настройки HTTP/3-проксирования, указанные на уровне `http` или
`server`, могли игнорироваться.
- При проксировании по протоколу HTTP/3 с включенной поддержкой NTLS директива
[proxy_ssl_certificate](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-certificate) не работала.
#### Изменения
- При плавном завершении старых рабочих процессов keepalive-соединения теперь
закрываются только после истечения таймаута, заданного директивой
[lingering_timeout](https://angie.software//angie/docs/configuration/modules/http/index.md#lingering-timeout). Такое поведение позволяет предотвратить возможные
ошибки на клиенте при получении ответа в этот момент. Спасибо Максиму Дунину
(freenginx).
- Отключено кэширование значений переменных stream-модуля
[$ssl_server_name](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-server-name), [$ssl_server_cert_type](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-server-cert-type),
[$ssl_preread_protocol](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#v-ssl-preread-protocol) и [$ssl_preread_server_name](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#v-ssl-preread-server-name), что
позволит получить актуальные значения при использовании виртуальных серверов.
#### Пакеты
- Добавлены динамические модули:
- [angie-pro-module-http-auth-radius](https://github.com/ten0s/ngx_http_auth_radius_module)
- Обновлены:
- [angie-pro-module-auth-jwt](https://angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) — до версии 0.8.0
- [angie-pro-module-jwt](https://angie.software//angie/docs/installation/external-modules/jwt.md#external-jwt) — до версии 3.4.2
- [angie-pro-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.8.8
- [angie-pro-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии 0.38.0
- [angie-pro-module-wasm](https://angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-core) — до версии 0.1-beta5
---
### Angie PRO 1.7.0
Дата выпуска: 19.09.2024.
#### Добавления
- Принудительное закрытие соединений к проксируемому серверу при удалении его из
группы; настраивается с помощью директив [proxy_connection_drop](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-connection-drop),
[grpc_connection_drop](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-connection-drop), [fastcgi_connection_drop](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-connection-drop),
[scgi_connection_drop](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-connection-drop) и [uwsgi_connection_drop](https://angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-connection-drop), значения которых
возможно индивидуально переопределить аргументом `connection_drop`
[API-запроса](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods) на удаление сервера.
- Счетчики отдельных типов отправленных DNS-запросов в API
статистики резолвера, собираемой параметром `status_zone` директивы
[resolver](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver).
- Режим балансировки [feedback (PRO)](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-feedback) теперь может быть использован и в
рамках `stream`-модуля; он распределяет TCP/UDP сессии с учетом значения
указанной переменной, которое может быть получено от проксируемых серверов или
периодического опроса внешних сервисов, что позволяет, в частности,
динамически перераспределять нагрузку в зависимости от произвольных метрик
проксируемого сервера: расхода различных ресурсов, загруженности CPU/памяти,
длины очереди и т.п.
- Опция `last_byte` директивы [feedback (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-feedback), позволяющая
анализировать ответ от проксируемых серверов не после получения
заголовка, а после получения ответа целиком.
- Метод балансировки [feedback (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-feedback) в качестве значения
переменной теперь поддерживает числа с плавающей запятой.
- Параметр `account` директивы [least_time (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-least-time), позволяющий гибко
указывать с помощью переменной, время ответа на какие запросы должно
учитываться в режиме балансировки `least_time`; в том числе дает
возможность учитывать время ответа только на определенные тестовые запросы
механизма [upstream_probe (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe).
- Параметр `factor` директивы [least_time (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-least-time), задающий коэффициент
сглаживания для балансировщика `least_time` и переопределяющий значение
директивы [response_time_factor (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor), которая используется для сбора
статистики.
- Режим `drain`, переводящий проксируемый stream-сервер в новое состояние
`draining`, при котором на сервер направляются только запросы,
привязанные с помощью модуля [sticky](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky).
- Переменная [$ssl_server_cert_type](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#v-ssl-server-cert-type), содержащая тип выбранного
сертификата при приеме TLS-соединения.
- Отключение создания PID-файла с помощью параметра `off` в директиве
[pid](https://angie.software//angie/docs/configuration/modules/core.md#pid), что может быть полезным для неизменяемых образов и при
непосредственном управлении менеджером процессов. Спасибо Максиму Дунину
(freenginx).
- Создание PID-файла теперь выполняется атомарно через
промежуточный временный файл, что исключает момент, когда файл уже
появился в директории, но еще пуст, и позволяет внешним программам
проще и надежнее с ним работать.
- Теперь при переконфигурации не делается попытка пересоздать PID-файл, если имя
в директиве [pid](https://angie.software//angie/docs/configuration/modules/core.md#pid) изменилось, но указывает на тот же файл через симлинки,
что, в частности, позволяет избежать проблем в системах во время миграции с
`/var/run/angie.pid` на `/run/angie.pid`. Спасибо Максиму Дунину
(freenginx).
- Ошибки [записи в syslog](https://angie.software//angie/docs/configuration/processing.md#syslog-logging) теперь логгируются не чаще
одного раза в секунду, что помогает предотвратить засорение логов подобными
сообщениями в случаях перегрузки или сбоя syslog-сервера. Спасибо Максиму
Дунину (freenginx).
- В почтовом прокси-сервере ограничено максимальное количество команд в процессе
аутентификации, задаваемое директивой [max_commands](https://angie.software//angie/docs/configuration/modules/mail/index.md#max-commands), для улучшения
защиты против DoS-атак. Спасибо Максиму Дунину (freenginx).
- Опция [--feature-cache](https://angie.software//angie/docs/installation/sourcebuild.md#configure) скрипта **./configure** для
кэширования результатов его работы с целью оптимизации массовой сборки модулей
или кросс-компиляции.
- Вся функциональность [nginx 1.27.1](https://nginx.org/ru/CHANGES.ru).
#### Исправления
- наступление таймаута ожидания в очереди, заданной директивой [queue (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-queue),
могло приводить к падению рабочего процесса.
- При запуске под systemd могли возникать ошибки `PID file ... not
readable (yet?) after start` и `Failed to parse PID from file...`.
Спасибо Максиму Дунину (freenginx).
#### Изменения
- Обновлены текстовые описания кодов HTTP-ответов в соответствии с RFC 9110.
Спасибо Максиму Дунину (freenginx) и Michiel W. Beijen.
- Теперь перед HTTP-запросом допускается не более одной пустой строки для
улучшения защиты против DoS-атак. Спасибо Максиму Дунину (freenginx).
- Запрещены имена полей заголовка HTTP/1.x без двоеточия на конце; такие
некорректные заголовки от клиента или проксируемого сервера теперь будут
приводить к возврату ошибки. Спасибо Максиму Дунину (freenginx) и Максиму
Евменкину.
- При чтении тела запроса с использованием HTTP/1.1 "chunked transfer encoding"
суммарный размер игнорируемых "chunk extensions" и полей "trailer header"
теперь ограничен директивой [client_max_body_size](https://angie.software//angie/docs/configuration/modules/http/index.md#client-max-body-size) для улучшения защиты
против DoS-атак. Спасибо Максиму Дунину (freenginx) и Bartek Nowotarski.
- MIME-тип в файле конфигурации `mime.types` для расширения `bmp` изменен
на `image/bmp`, для расширения `rar` u2014 на
`application/vnd.rar`, а для расширений `deb` и `udeb`
теперь указан `application/vnd.debian.binary-package`. Спасибо Юрию
Изоркину.
#### Пакеты
- Обновлены:
- [angie-pro-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии 0.36.0
- [angie-pro-module-lua](https://angie.software//angie/docs/installation/external-modules/lua.md#external-lua) — до версии 0.10.27
24.10.2024
- Пакеты для операционной системы [SberLinux](https://angie.software//angie/docs/installation/pro_packages.md#install-yum-pro).
---
### Angie PRO 1.6.2
Дата выпуска: 16.08.2024.
#### Безопасность
- Обработка специально созданного MP4-файла модулем
[ngx_http_mp4_module](https://angie.software//angie/docs/configuration/modules/http/http_mp4.md#http-mp4)
могла приводить к падению рабочего процесса
([CVE-2024-7347](https://nvd.nist.gov/vuln/detail/CVE-2024-7347));
исправление портировано из nginx 1.27.1.
---
### Angie PRO 1.6.1
Дата выпуска: 08.08.2024.
#### Добавления
- Счетчик `passed` в зоне
[API статистики](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-server-zones), задаваемой
директивой [status_zone](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone) модуля [stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream),
для подсчета соединений, переданных на обработку в другие слушающие сокеты
при помощи директив [pass](https://angie.software//angie/docs/configuration/modules/stream/stream_pass.md#s-pass).
#### Исправления
- При использовании виртуальных серверов или директивы [pass](https://angie.software//angie/docs/configuration/modules/stream/stream_pass.md#s-pass)
в модуле [stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream)
соединения могли учитываться некорректно в API статистики.
- На конфигурациях с 5 ACME-клиентами и более могли
происходить падения рабочих процессов; проблема появилась в 1.6.0.
- Обработка закэшированных ответов с заголовком
`X-Accel-Redirect` могла приводить к падению рабочего процесса.
Спасибо Максиму Дунину (freenginx) и Иржи Сетничке.
#### Пакеты
- Обновлены:
- [angie-pro-console-light](https://angie.software//angie/docs/installation/pro_packages.md#install-console-light-pro) — до версии 1.4.0
- [angie-pro-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии 0.35.3
- [angie-pro-module-zstd](https://angie.software//angie/docs/installation/external-modules/zstd.md#external-zstd) — до ревизии `f4ba115`
---
### Angie PRO 1.6.0
Дата выпуска: 28.06.2024.
#### Добавления
- Балансировка HTTP-запросов с учетом значения указанной переменной,
которое может быть получено от проксируемых серверов
или периодического опроса внешних сервисов,
настраиваемая с помощью директивы [feedback](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-feedback)
в блоке [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream);
что позволяет, в частности, динамически перераспределять нагрузку
в зависимости от произвольных метрик проксируемого сервера:
расхода различных ресурсов, загруженности CPU/памяти, длинны очереди и т.п.
- Директива [sticky](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky) и сопутствующие настройки в блоке
[upstream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) [stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream)-модуля,
позволяющие задать режим привязки сессий,
при котором все соединения в рамках сессии
будут направляться на один и тот же сервер.
- Извлечение значений Cookie из RDP-соединений с помощью
директивы [rdp_preread](https://angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#s-rdp-preread) [stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream)-модуля
в переменные [$rdp_cookie](https://angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#v-rdp-cookie) и
[$rdp_cookie_NAME](https://angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#id5),
что позволяет логировать и привязывать RDP-сеансы клиентов
к одним и тем же серверам при балансировке нагрузки.
- Опция `persistent` директивы [upstream_probe](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe),
позволяющая не ждать прохождения проверки `essential`
после перезагрузки конфигурации для ранее работоспособных серверов.
- Возможность указать несколько директив [acme](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#id4)
в одном блоке [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server),
что позволяет настраивать получение сертификатов сразу двух типов
в рамках данного виртуального сервера.
- Ключи командной строки `-m` и `-M`
для отображения списка встроенных и загруженных модулей.
- Переменная [$upstream_probe](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe),
которая содержит имя текущей активной проверки,
порожденной [upstream_probe](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe).
- Поддержка [BoringSSL](https://www.chromium.org/Home/chromium-security/boringssl/)
в модуле [ACME](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme).
- Вся функциональность [nginx 1.27.0](https://nginx.org/ru/CHANGES.ru),
включая поддержку виртуальных серверов в модуле [stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream)
и директиву `pass`,
позволяющую передавать принятые соединения на обработку в другие слушающие сокеты,
в том числе модулей [HTTP](https://angie.software//angie/docs/configuration/modules/index.md#modules-http) и [Mail](https://angie.software//angie/docs/configuration/modules/index.md#modules-mail).
#### Исправления
- Активные проверки [upstream_probe](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)
могли не работать на некоторых конфигурациях, логируя при этом ошибки вида
`[alert] getsockname() failed (9: Bad file descriptor)`.
- Запрос сертификата по протоколу ACME мог завершаться ошибкой
в некоторых конфигурациях с сообщением в логе вида
`[alert] getsockname() failed (9: Bad file descriptor)`.
- Запрос сертификата с большим количеством доменных имен по протоколу ACME
мог завершаться ошибкой с сообщением в логе вида
`[error] JSON parser error`.
- ACME-клиенты в конфигурациях с несколькими директивами
[error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log)
могли выводить сообщения в несоответствующие логи.
#### Пакеты
- Обновлены:
- [angie-pro-module-auth-jwt](https://angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) — до версии 0.7.0
- [angie-pro-module-auth-ldap](https://angie.software//angie/docs/installation/external-modules/auth-ldap.md#external-ldap) — до ревизии `241200e`
- [angie-pro-module-jwt](https://angie.software//angie/docs/installation/external-modules/jwt.md#external-jwt) — до версии 3.4.1
- [angie-pro-module-keyval](https://angie.software//angie/docs/installation/external-modules/keyval.md#external-keyval) — до версии 0.3.0
- [angie-pro-module-lua](https://angie.software//angie/docs/installation/external-modules/lua.md#external-lua):
`stream_lua_module` — до ревизии `bea8a0c`
- [angie-pro-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.8.5
---
### Angie PRO 1.5.2
Дата выпуска: 03.06.2024.
#### Безопасность
- При использовании HTTP/3 обработка специально созданной
QUIC-сессии могла приводить к падению рабочего процесса, отправке
клиенту содержимого памяти рабочего процесса на системах с MTU больше
4096 байт и иметь другие последствия
([CVE-2024-32760](https://nvd.nist.gov/vuln/detail/CVE-2024-32760),
[CVE-2024-31079](https://nvd.nist.gov/vuln/detail/CVE-2024-31079),
[CVE-2024-35200](https://nvd.nist.gov/vuln/detail/CVE-2024-35200),
[CVE-2024-34161](https://nvd.nist.gov/vuln/detail/CVE-2024-34161));
исправление портировано из nginx 1.26.1.
#### Пакеты
- Обновлены:
- [angie-pro-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии 0.35.2
---
### Angie PRO 1.5.1
Дата выпуска: 16.05.2024.
#### Исправления
- Механизм `proxy_next_upstream` работал некорректно при редактировании
группы проксируемых серверов через API, а также при использовании опции
[resolve](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-reresolve) директивы `server` в блоке
`upstream`, если количество полученных IP-адресов отличалось от числа
заданных серверов.
- При запросе сертификата по протоколу ACME могла
произойти ошибка сегментации в рабочем процессе.
- Директива [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) в режиме `learn` могла работать
некорректно с различающимся количеством переменных `lookup` и
`create`.
- Механизм [slow_start](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-slow-start) не срабатывал при проксировании
TCP-соединений в модуле [stream](https://angie.software//angie/docs/configuration/modules/index.md#modules-stream).
- Запросы HTTP/3 могли завершаться с ошибкой, если они
были присланы как TLS 1.3 early data; проблема появилась в 1.4.0.
- HTTP/3-соединение могло закрываться преждевременно при
использовании 0-RTT в QUIC.
- При чтении тела запроса из быстрого соединения было
возможно чтение в течение долгого времени. Спасибо Максиму Дунину
(freenginx).
#### Изменения
- Теперь ACME-клиенты не игнорируют ранее сохраненные
сертификаты, если они просрочены или выпущены для отличающегося
списка доменных имен, а используют их, пока идет обновление.
#### Пакеты
27.05.2024
- Пакеты для операционной системы [Alpine](https://angie.software//angie/docs/installation/pro_packages.md#install-alpine-pro) 3.20.
---
### Angie PRO 1.5.0
Дата выпуска: 27.03.2024.
#### Добавления
- Начальная поддержка автоматического получения и обновления сертификатов по
[протоколу ACME](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme), конфигурируемая с
помощью директив [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) и [acme](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#id4), а также переменных вида
[$acme_cert_=](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-name) и [$acme_cert_key_=](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-key-name).
- режим `drain`, переводящий проксируемый HTTP-сервер в новое состояние
`draining`, при котором на сервер направляются только запросы,
привязанные с помощью модуля [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky).
- Настройка автоматического перенаправления для добавления
слеша в конец URI запроса с помощью директивы [auto_redirect](https://angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect).
- Вывод содержащих даты [метрик](https://angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) в формате временных меток Unix
вместо ISO 8601 для использования в Prometheus, а также в JSON API при запросе
с аргументом `?date-epoch`.
- Теперь ключ `-V` показывает также релевантную версию nginx, что
полезно для совместимости со сторонними утилитами, в частности
**certbot**. Спасибо [AdvTechnoKing](https://github.com/webserver-llc/angie/commit/eb914d43aa6a2231d7321c808cb4180abb013ca0).
- Вся функциональность [nginx 1.25.4](https://nginx.org/ru/CHANGES.ru).
#### Исправления
- Если был задействован механизм переиспользования SSL-сессий
([proxy_ssl_session_reuse](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-session-reuse)), то при динамическом обновлении списка
проксируемых серверов могла происходить утечка из зоны разделяемой памяти
(`zone`), настроенной для соответствующего блока `upstream`.
#### Пакеты
- Пакеты для операционных систем [FreeBSD 13](https://angie.software//angie/docs/installation/pro_packages.md#install-freebsd-pro) (arm64),
[RED OS 8](https://angie.software//angie/docs/installation/pro_packages.md#install-yum-pro) (x86-64).
- Добавлены динамические модули:
- [angie-pro-module-otel](https://github.com/nginxinc/nginx-otel)
- Обновлены:
- [angie-pro-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии 0.34.0
28.03.2024
- Обновлены:
- [angie-pro-console-light](https://angie.software//angie/docs/installation/pro_packages.md#pro-packages) — до версии 1.3.0
16.04.2024
- Добавлены динамические модули:
- [angie-pro-module-zstd](https://github.com/tokers/zstd-nginx-module)
- Обновлены:
- [angie-pro-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.8.4
25.04.2024
- Добавлены динамические модули:
- angie-pro-module-vts: включает
[module-vts](https://github.com/vozlt/nginx-module-vts),
[module-sts](https://github.com/vozlt/nginx-module-sts),
[module-stream-sts](https://github.com/vozlt/nginx-module-stream-sts)
---
### Angie PRO 1.4.1
Дата выпуска: 15.02.2024.
#### Безопасность
- При использовании HTTP/3 в рабочем процессе во время обработки специально
созданной QUIC-сессии могла произойти ошибка сегментации
([CVE-2024-24989](https://nvd.nist.gov/vuln/detail/CVE-2024-24989));
при этом Angie PRO, начиная еще с версии 1.4.0, не подвержен уязвимости
[CVE-2024-24990](https://nvd.nist.gov/vuln/detail/CVE-2024-24990).
#### Пакеты
- Добавлены динамические модули:
- [angie-pro-module-dynamic-limit-req](https://github.com/limithit/ngx_dynamic_limit_req_module)
- Обновлены:
- [angie-pro-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.8.3
- [angie-pro-module-vod](https://angie.software//angie/docs/installation/external-modules/vod.md#external-vod) — до версии 1.33
## 2023
### Angie PRO 1.4.0
Дата выпуска: 21.12.2023.
#### Добавления
- Поддержка [HTTP/3](https://angie.software//angie/docs/configuration/modules/http/http_v3.md#http-v3)-соединений с `upstream`-серверами в
[прокси-модуле HTTP](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy), допускающая использование клиентами
произвольных версий HTTP. Конфигурация осуществляется с помощью директивы
[proxy_http_version](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version) и набора директив `proxy_quic_` и
`proxy_http3_`.
- Директива [upstream_probe (PRO)](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe) для активной проверки состояния серверов в
блоке `upstream` [stream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream)-модуля путем
периодического создания тестовых соединений или отправки датаграмм.
- Дополнительный режим работы `learn` директивы [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky)
для привязки сессий к проксируемым серверам, позволяющий обнаруживать
сессии и запоминать их в разделяемой памяти сервера.
- Очередь ожидания для запросов, для которых не удалось выбрать проксируемый
сервер с первой попытки, настраиваемая с помощью директивы [queue (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-queue) в
блоке `upstream` [HTTP](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream)-модуля.
- HTTP RESTful [JSON-интерфейс](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-stream-upstreams-servers) для
изменения конфигурации, добавления и удаления проксируемых серверов в блоках
`upstream` [stream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream)-модуля, а также директива
[state](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-state) для долговременного сохранения этих изменений.
- Балансировка с учетом среднего времени установки соединения, получения первого
или последнего байта ответа от проксируемых [stream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream)-серверов с настраиваемым коэффициентом сглаживания,
использующая директивы [least_time (PRO)](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-least-time) и [response_time_factor (PRO)](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor)
в блоке `upstream`.
- Статистика по среднему времени установки соединения, получения первого и
последнего байта ответа от проксируемых [stream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream)-серверов в интерфейсе, предоставляемом директивой [api](https://angie.software//angie/docs/configuration/modules/http/http_api.md#a-api), с возможностью настройки коэффициента сглаживания директивой
[response_time_factor (PRO)](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) блока `upstream`.
- Механизм плавного ввода проксируемого сервера в работу после сбоя с помощью
опции `slow_start` директивы [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) в блоке
`upstream`.
- Директива [mqtt_preread](https://angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#s-mqtt-preread) модуля [stream](https://angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#stream-mqtt-preread),
позволяющая помещать имя пользователя и идентификатор клиента из пакета
CONNECT протокола MQTT в переменные [$mqtt_preread_username](https://angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#v-mqtt-preread-username) и [$mqtt_preread_clientid](https://angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#v-mqtt-preread-clientid).
- Ограничение скорости отдачи MP4-файлов клиенту
пропорционально битрейту с помощью директив [mp4_limit_rate](https://angie.software//angie/docs/configuration/modules/http/http_mp4.md#mp4-limit-rate) и
[mp4_limit_rate_after](https://angie.software//angie/docs/configuration/modules/http/http_mp4.md#mp4-limit-rate-after), снижающее нагрузку на полосу пропускания.
- Вся функциональность [nginx 1.25.3](https://nginx.org/ru/CHANGES.ru).
#### Исправления
- Если проксируемый сервер был единственным в группе, то он мог некорректно
учитываться как `unavailable` в [API статистики](https://angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) даже
после восстановления работоспособности.
#### Изменения
- Теперь время, в течение которого проксируемый сервер
находился в состоянии `checking`, не учитывается в `downtime`.
- В стандартный шаблон [prometheus_all.conf](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#prometheus-all) добавлены все
дополнительные метрики Prometheus и возможные значения `state` у
серверов `upstream`, присутствующие только в версии PRO.
#### Пакеты
- Пакеты для операционной системы [Alpine](https://angie.software//angie/docs/installation/pro_packages.md#install-alpine-pro) 3.19.
- Обновлены:
- [angie-pro-console-light](https://angie.software//angie/docs/installation/pro_packages.md#pro-packages) — до версии 1.2.0
- [angie-pro-module-auth-jwt](https://angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) — до версии 0.4.0
- [angie-pro-module-headers-more](https://angie.software//angie/docs/installation/external-modules/headers-more.md#external-headers-more) — до версии 0.36
- [angie-pro-module-ndk](https://angie.software//angie/docs/installation/external-modules/ndk.md#external-ndk) — до версии 0.3.3
- [angie-pro-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии 0.33.0
25.12.2023
- Обновлены:
- [angie-pro-console-light](https://angie.software//angie/docs/installation/pro_packages.md#pro-packages) — до версии 1.2.1
22.01.2024
- Добавлены динамические модули:
- [angie-pro-module-zip](https://github.com/evanmiller/mod_zip)
- Обновлены:
- [angie-pro-module-auth-jwt](https://angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) — до версии 0.6.0
- [angie-pro-module-headers-more](https://angie.software//angie/docs/installation/external-modules/headers-more.md#external-headers-more) — до версии 0.37
- [angie-pro-module-lua](https://angie.software//angie/docs/installation/external-modules/lua.md#external-lua):
`http_lua_module` — до версии 0.10.26;
`stream_lua_module` — до версии 0.0.14
---
### Angie PRO 1.3.2
Дата выпуска: 23.11.2023.
#### Исправления
- [Активные проверки](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe) с флагом `essential` при
обнаружении изначальной проблемы некорректно обрабатывали смену состояния
проксируемого сервера с `checking` на `unhealthy`, из-за чего
пользовательские запросы могли направляться на неработоспособный сервер.
- Были возможны некорректные значения метрик в формате [Prometheus](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#id3), в значениях которых использовались отличные от `$p8s_value`
переменные; на практике проблема могла наблюдаться с
`angie_http_upstreams_peers_state` и `angie_stream_upstreams_peers_state`
из стандартного шаблона `prometheus_all.conf`.
- Некоторые попытки соединения с проксируемыми серверами могли не учитываться
соответствующим образом в [API статистики](https://angie.software//angie/docs/configuration/modules/http/http_api.md#a-api), если ошибка
происходила моментально; проблема появилась в 1.3.0.
#### Пакеты
04.12.2023
- Добавлены динамические модули:
- [angie-pro-module-modsecurity](https://github.com/owasp-modsecurity/ModSecurity-nginx)
07.12.2023
- Обновлены:
- [angie-pro-console-light](https://angie.software//angie/docs/installation/pro_packages.md#pro-packages) — до версии 1.1.1
12.12.2023
- Добавлены динамические модули:
- [angie-pro-module-auth-ldap](https://github.com/kvspb/nginx-auth-ldap)
- Обновлены:
- [angie-pro-module-auth-jwt](https://angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) — до версии 0.4.0
- [angie-pro-module-headers-more](https://angie.software//angie/docs/installation/external-modules/headers-more.md#external-headers-more) — до версии 0.36
- [angie-pro-module-ndk](https://angie.software//angie/docs/installation/external-modules/ndk.md#external-ndk) — до версии 0.3.3
- [angie-pro-module-opentracing](https://angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) — до версии 0.33.0
---
### Angie PRO 1.3.1
Дата выпуска: 18.10.2023.
#### Безопасность
- Добавлены дополнительные ограничения при обработке потоков HTTP/2, чтобы
лучше противостоять DoS-атаке "HTTP/2 Rapid Reset" ([CVE-2023-44487](https://nvd.nist.gov/vuln/detail/CVE-2023-44487)).
#### Пакеты
26.10.2023
- Добавлены динамические модули:
- [angie-pro-module-opentracing](https://github.com/opentracing-contrib/nginx-opentracing/)
13.11.2023
- Добавлены динамические модули:
- [angie-pro-module-testcookie](https://github.com/kyprizel/testcookie-nginx-module/)
- Обновлены:
- [angie-pro-console-light](https://angie.software//angie/docs/installation/pro_packages.md#pro-packages) — до версии 1.1.0
- [angie-pro-module-headers-more](https://angie.software//angie/docs/installation/external-modules/headers-more.md#external-headers-more) — до версии 0.35
- [angie-pro-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.8.2
- [angie-pro-module-vod](https://angie.software//angie/docs/installation/external-modules/vod.md#external-vod) — до версии 1.32
---
### Angie PRO 1.3.0
Дата выпуска: 03.10.2023.
#### Добавления
- Возможность указывать в директиве `location` несколько строк для
сопоставления, что позволяет [объединить](https://angie.software//angie/docs/configuration/modules/http/index.md#combined-locations) несколько
блоков `location` с одинаковыми настройками и, таким образом, упростить
конфигурацию за счет уменьшения дублирования.
- Балансировка с учетом среднего времени получения
заголовка ответа или полного ответа от проксируемых HTTP-серверов с
настраиваемым коэффициентом сглаживания, использующая директивы
[least_time (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-least-time) и [response_time_factor (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) в блоке `upstream`.
- Экспорт различных метрик статистики в формате Prometheus
с гибко настраиваемыми шаблонами при помощи новых директив
[prometheus](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#id3) и [prometheus_template](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#prometheus-template).
- Статистика по среднему времени получения заголовка ответа
и полного ответа от проксируемых HTTP-серверов в интерфейсе,
предоставляемом директивой [api](https://angie.software//angie/docs/configuration/modules/http/http_api.md#a-api), с возможностью настройки
коэффициента сглаживания директивой [response_time_factor (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) блока
`upstream`.
- Детальная информация и [метрики](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-upstreams) по
группам проксируемых stream-серверов в интерфейсе статистики, предоставляемом
директивой [api](https://angie.software//angie/docs/configuration/modules/http/http_api.md#a-api).
- Опция [resolve](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-reresolve) директивы `server` в блоке `upstream`
модуля [stream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream), позволяющая отслеживать изменения
списка IP-адресов, соответствующего доменному имени, и автоматически
обновлять его без перезагрузки конфигурации.
- Опция [service](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-reresolve) директивы `server` в блоке `upstream`
модуля [stream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream), позволяющая получать списки адресов
из DNS-записей SRV, с базовой поддержкой приоритета.
- Возможность привязки клиентских соединений к соединению с
проксируемым сервером с помощью директивы [bind_conn (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-bind-conn) в блоках
`upstream` [HTTP](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream)-модуля, позволяющая, в частности,
успешно проксировать соединения с проверкой подлинности NT LAN Manager (NTLM).
- Получение содержимого конфигурационных файлов, с которыми
было запущено текущее поколение рабочих процессов, в интерфейсе,
предоставляемом директивой [api](https://angie.software//angie/docs/configuration/modules/http/http_api.md#a-api) при включении директивы
[api_config_files](https://angie.software//angie/docs/configuration/modules/http/http_api.md#a-api-config-files).
- Отображение номера [поколения конфигурации](https://angie.software//angie/docs/configuration/runtime.md#control-config-change) в
именах процессов, что позволяет с помощью утилиты `ps` отслеживать успех
перезагрузок конфигурации и количество поколений рабочих процессов с
предыдущими версиями конфигурации.
- Вся функциональность [nginx 1.25.2](https://nginx.org/ru/CHANGES.ru).
#### Изменения
- Теперь при загрузке конфигурации OpenSSL используется
appname `angie`.
#### Пакеты
- Обновлены:
- [angie-pro-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.8.1
---
### Angie PRO 1.2.0
Дата выпуска: 15.08.2023.
#### Добавления
- [HTTP RESTful JSON интерфейс](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-config) для изменения конфигурации,
добавления и удаления проксируемых серверов в блоках [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream)
[HTTP](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream)-модуля, а также директива [state](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-state)
для долговременного сохранения этих изменений.
- Директива [upstream_probe (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe) для активной проверки состояния серверов в
блоке [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) [HTTP](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream)-модуля путем отправки
периодических тестовых запросов.
- Поддержка сегментирования кэша в модуле [HTTP](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) proxy,
которая позволяет в зависимости от произвольного параметра ответа кэшировать
его на разных директориях (дисках), задаваемых дополнительным параметром
`path-` директивы [proxy_cache](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache) с использованием переменных.
- Поддержка NTLS в [HTTP](https://angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#stream-ssl) модулях
при использовании TLS библиотеки [TongSuo](https://github.com/Tongsuo-Project/Tongsuo), включаемая параметром сборки
`‑‑with‑ntls` и настраиваемая с помощью соответствующих директив
[ssl_ntls](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ntls) и [proxy_ssl_ntls](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-ntls).
- В [HTTP](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#stream-proxy) прокси-модулях
теперь можно настраивать несколько сертификатов разного типа (RSA и ECDSA) и
соответствующих им ключей, используя директивы [proxy_ssl_certificate](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-certificate) и
[proxy_ssl_certificate_key](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-certificate-key).
- Вывод версии и сборки в отображаемом имени `master` процесса, что позволяет
с помощью утилиты `ps` получить эту информацию о работающем экземпляре
сервера.
- Возможность сжатия модулем [gzip](https://angie.software//angie/docs/configuration/modules/http/http_gzip.md#http-gzip) ответов со статусом "207
Multi-Status". Спасибо
[DBotThePony](https://github.com/webserver-llc/angie/pull/26).
- Вся функциональность [nginx 1.25.0](https://nginx.org/ru/CHANGES.ru),
включая поддержку [HTTP/3](https://angie.software//angie/docs/configuration/modules/http/http_v3.md#http-v3).
#### Изменения
- Значения переменной [$upstream_sticky_status](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-sticky-status) теперь в верхнем регистре,
чтобы быть в одном стиле со значениями [$upstream_cache_status](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-cache-status).
#### Пакеты
- Добавлены динамические модули:
- [angie-pro-module-enhanced-memcached](https://github.com/bpaquet/ngx_http_enhanced_memcached_module)
- [angie-pro-module-eval](https://github.com/openresty/nginx-eval-module)
---
### Angie PRO 1.1.0-p1
Дата выпуска: 01.03.2023.
#### Добавления
- Директива [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) и сопутствующие настройки в блоке
[upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) [HTTP](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream)-модуля, позволяющие задать режим
привязки сессий, при котором все запросы в рамках сессии будут направляться на
один и тот же сервер.
- Переменная [$upstream_sticky_status](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-upstream-sticky-status), принимающая значения `new`,
`hit` или `miss` в зависимости от успеха направления запроса на
релевантный проксируемый сервер с включенной привязкой сессий.
---
### Angie PRO 1.1.0
Дата выпуска: 07.02.2023.
#### Добавления
- Директива [api](https://angie.software//angie/docs/configuration/modules/http/http_api.md#a-api), реализующая HTTP RESTful интерфейс для получения в
форматах JSON или Prometheus базовой информации о веб-сервере, а также
[статистики](https://angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) по клиентским соединениям, зонам разделяемой
памяти, DNS-запросам, HTTP-запросам, кэшу HTTP-ответов, сессиям модуля
[stream](https://angie.software//angie/docs/configuration/modules/stream/index.md#stream-core), зонам модулей [limit_conn](https://angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#http-limit-conn)/[limit_req](https://angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req) и группам
[проксируемых HTTP-серверов](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).
- Опция [resolve](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) директивы [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) в блоке
[upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) [HTTP](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream)-модуля, позволяющая отслеживать
изменения списка IP-адресов, соответствующего доменному имени, и
автоматически обновлять его
без перезагрузки конфигурации.
- Опция [service](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) директивы [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) в блоке
[upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) [HTTP](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream)-модуля, позволяющая получать
списки адресов из DNS SRV записей,
с базовой поддержкой приоритета.
- Директива [status_zone](https://angie.software//angie/docs/configuration/modules/http/index.md#status-zone) в модуле [HTTP](https://angie.software//angie/docs/configuration/modules/http/index.md#http-core)
для указания зоны сбора статистики по запросам в [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server) и
[location](https://angie.software//angie/docs/configuration/modules/http/index.md#location) контекстах.
- Директива [status_zone](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone) в модуле [stream](https://angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) для указания зоны сбора статистики по TCP/UDP сессиям.
- Параметр [status_zone](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver-status) директивы [resolver](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver) для
указания зоны сбора статистики по DNS-запросам.
- [autoindex](https://angie.software//angie/docs/configuration/modules/http/http_autoindex.md#id3) выводит листинги директорий в естественном порядке.
- Произвольная настройка подписи на стандартных страницах ошибок и поля
`Server` в заголовке ответа с помощью директивы [server_tokens](https://angie.software//angie/docs/configuration/modules/http/index.md#server-tokens).
- Переменная [$angie_version](https://angie.software//angie/docs/configuration/modules/http/index.md#v-angie-version), содержащая версию Angie.
- Вся функциональность [nginx 1.23.3](https://nginx.org/ru/CHANGES.ru).
#### Пакеты
07.04.2023
- Пакеты для операционной системы [ALT](https://angie.software//angie/docs/installation/pro_packages.md#install-alt-pro) Linux.
12.05.2023
- Пакеты для операционной системы [FreeBSD](https://angie.software//angie/docs/installation/pro_packages.md#install-freebsd-pro).
- Добавлены динамические модули:
- [angie-pro-module-subs](https://github.com/yaoweibin/ngx_http_substitutions_filter_module)
- [angie-pro-module-upload](https://github.com/fdintino/nginx-upload-module)
- [angie-pro-module-vod](https://github.com/kaltura/nginx-vod-module)
26.05.2023
- Пакеты для операционной системы [Astra](https://angie.software//angie/docs/installation/pro_packages.md#install-astrase-pro) Linux Special Edition.
13.06.2023
- Пакеты для операционных систем [Debian 12 "Bookworm"](https://angie.software//angie/docs/installation/pro_packages.md#install-deb-pro) и
[AlmaLinux](https://angie.software//angie/docs/installation/pro_packages.md#install-yum-pro).
12.07.2023
- Добавлены динамические модули:
- [angie-pro-module-cache-purge](https://github.com/nginx-modules/ngx_cache_purge)
- [angie-pro-module-echo](https://github.com/openresty/echo-nginx-module)
- [angie-pro-module-keyval](https://github.com/kjdev/nginx-keyval)
- [angie-pro-module-postgres](https://github.com/FRiCKLE/ngx_postgres)
- Обновлены:
- [angie-pro-module-njs](https://angie.software//angie/docs/installation/external-modules/njs.md#external-njs) — до версии 0.8.0
31.07.2023
- Добавлены динамические модули:
- [angie-pro-module-auth-jwt](https://github.com/kjdev/nginx-auth-jwt)
# https://angie.software/anic/docs.md
# О решении Angie Ingress Controller
Angie Ingress Controller (ANIC) — это решение для управления трафиком контейнеризированных
приложений в Kubernetes. ANIC развертывается и работает в кластере, управляя функциями
Ingress с возможностью настройки правил обработки трафика.
ANIC базируется в своей работе на [Angie PRO](/angie/pro/) —
эффективном, мощном и масштабируемом веб-сервере.
ANIC использует широкий набор функций Ingress:
- Балансировка нагрузки TCP, UDP, TLS, HTTP, gRPC (гибкое распределение трафика
и его плавного переноса при обновлениях приложений).
- Терминация сессий TLS (подтверждения подлинности сервисов и защиты онлайн-транзакций).
- Настройки гибкого логирования (управление современными динамическими приложениями).
- Расширенная маршрутизация трафика (разделение трафика и расширенная
маршрутизация на основе содержимого).
- Ограничение поступающего трафика (по различным критериям для защиты приложений от DDoS).
- Модификация ответов на запросы (на уровне балансировщика HTTP).
## Особенности ANIC
- Расширенная статистика и real-time мониторинг: возможность полного мониторинга
нагрузки Ingress в режиме реального времени, что позволяет управлять
конфигурациями по профилю нагрузки и соблюдать полную доступность сервисов.
- Активная проверка состояния проксируемых серверов: проверка на "живучесть"
и проксирование только на те upstream, которые отвечают заданному алгоритму.
- Проксирование с привязкой сессий: возможность задать режим привязки сессий
через директиву sticky и сопутствующие настройки в блоке upstream модуля HTTP.
- Аутентификация пользователей с использованием OIDC (OpenID Connect) и JWT (JSON Web Token).
## Текущая версия
Текущая версия — ANIC
```
|anic_pdf_version|
```
.
Также см. [полную историю версий ANIC](https://angie.software//anic/docs/changes.md#anic-changes).
## Поддерживаемые дистрибутивы
| Название | Версии | Архитектуры |
|--------------|-----------------|---------------|
| Alpine Linux | `3.21` | x86_64, ARM64 |
| Debian | `11` "Bullseye" | x86_64, ARM64 |
| ALT Linux | `10` | x86_64, ARM64 |
#### NOTE
Документация ANIC доступна в машиночитаемом виде для
LLM-инструментов (`llms.txt`, `llms-full.txt`,
Markdown-версии страниц) — подробности в разделе
[Документация для языковых моделей](https://angie.software//angie/docs/configuration/index.md#llm-resources).
Карточка ANIC в реестре
[Context7](https://context7.com/):
[https://context7.com/websites/angie_software_anic](https://context7.com/websites/angie_software_anic).
# https://angie.software/anic/docs/how-anic-works.md
# Как работает Angie Ingress Controller
Этот документ описывает работу *Angie Ingress Controller*, также
*ANIC*, построенного на возможностях веб-сервера Angie.
Мы предполагаем, что читатель знаком с основными концепциями Kubernetes,
такими как Pod, Deployment, Service и Endpoints.
## Что такое Ingress Controller
Ingress Controller - это компонент в кластере Kubernetes, который
настраивает балансировщик нагрузки HTTP в соответствии с ресурсами
Ingress, созданными пользователем кластера.
> Чтобы узнать больше о ресурсах Ingress, обратитесь к [официальной
> документации Kubernetes](https://kubernetes.io/docs/concepts/services-networking/ingress/).
## Angie Ingress Controller на высоком уровне
Давайте начнем с общего изучения ANIC. Рассмотрим пример того, как ANIC
предоставляет клиентам в интернете доступ к двум веб-приложениям,
запущенным в кластере Kubernetes.
В схеме участвуют:
- Кластер *Kubernetes*.
- Пользователи кластера: *администратор*, *пользователь A* и
*пользователь B*, которые используют кластер через *API Kubernetes*.
- *Клиенты A* и *клиенты B*, которые подключаются к *приложениям A* и
*приложениям B*, развернутым соответствующими пользователями.
- *ANIC*, развернутый администратором в Pod в пространстве имен *angie-ingress*
и настроенный с помощью ресурса *ConfigMap angie-ingress*. Для простоты мы
изобразили только один Pod ANIC, однако *администратор* обычно развертывает
по крайней мере два Pod для обеспечения избыточности. *ANIC* использует *API
Kubernetes* для получения последних ресурсов Ingress, созданных в кластере, а
затем настраивает *Angie* в соответствии с этими ресурсами.
- *Приложение A* с двумя Pod, развернутыми в *пространстве имен A*
*пользователем A.* Чтобы предоставить доступ приложению к его
клиентам ( *клиентам A*) через хост `a.example.com` , *пользователь
A* создает *ресурс Ingress A.*
- *Приложение B* с одним Pod, развернутым в *пространстве имен B*
*пользователем B.* Чтобы предоставить доступ к приложению его
клиентам ( *клиентам B*) через хост `b.example.com`, *пользователь
B* создает *ресурс VirtualServer B*.
- *Общедоступная конечная точка*, которая находится перед Pod-ами
*ANIC*. Обычно это TCP-балансировщик нагрузки (облачный, программный
или аппаратный) или комбинация такого балансировщика нагрузки с
сервисом NodePort. *Клиенты A* и *клиенты B* подключаются к своим
приложениям через *общедоступную конечную точку*.
Для простоты не учтены многие необходимые ресурсы Kubernetes, такие
как Deployment и Service, которые администратору и пользователям
также необходимо создать.
Далее исследуем Pod ANIC.
## Pod ANIC
Pod ANIC состоит из одного контейнера, который, в свою очередь, включает
в себя следующее:
- *Процесс ANIC*, который настраивает Angie в соответствии с Ingress и
другими ресурсами, созданными в кластере.
- *Главный процесс Angie*, который управляет рабочими процессами Angie.
- *Рабочие процессы Angie*, которые обрабатывают клиентский трафик и
балансируют нагрузку на серверные приложения.
В приведенной ниже таблице описано каждое соединение с
указанием его типа:
| № | Тип соединения | Описание |
|-----|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| | HTTP | *Prometheus* извлекает метрики ANIC и Angie через конечную
точку HTTP, которую предоставляет *ANIC*.
#### NOTE
*Prometheus* не требуется для ANIC, и эту конечную точку можно
отключить. |
| | HTTPS | *ANIC* обращается к *API Kubernetes*, чтобы получить
последние версии ресурсов в кластере, и выполняет запись в API для
обновления статусов обрабатываемых ресурсов и выдачи событий. |
| | HTTP | *Kubelet* проверяет готовность *ANIC* (значение по умолчанию
`:8081/angie-ready`), чтобы определить
[готовность](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-conditions)
Pod ANIC. |
| | Файловый ввод-вывод | Когда *ANIC* запускается, он считывает из
файловой системы *шаблоны конфигурации*, необходимые для генерации
конфигурации. Шаблоны расположены в каталоге `/` контейнера и
имеют расширение `.tmpl`. |
| | Файловый ввод-вывод | *ANIC* записывает в свои потоки *stdout* и
*stderr* журналы, которые собираются средой выполнения контейнеров. |
| | Файловый ввод-вывод | *ANIC* генерирует *конфигурацию* Angie на
основе ресурсов, созданных в кластере и записывает ее в файловую
систему в папке `/etc/angie`. Файлы конфигурации имеют расширение
`.conf`. |
| | Файловый ввод-вывод | *ANIC* записывает *TLS-сертификаты* и *ключи*
из всех [секретов
TLS](https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets),
на которые ссылаются ресурсы Ingress и другие ресурсы, в файловую
систему. |
| | HTTP | *ANIC* извлекает [метрики Angie](https://angie.software//angie/docs/configuration/modules/http/http_stub_status.md#id3) через UNIX-сокет
`unix:/var/lib/angie/angie-status.socket` и преобразует их в формат
Prometheus, используемый в п.1. |
| | HTTP | Чтобы убедиться в успешности перезагрузки конфигурации,
*ANIC* проверяет, что по крайней мере у одного *рабочего процесса
Angie* есть новая конфигурация. Для этого *ANIC* проверяет
конкретную конечную точку через UNIX-сокет
`unix:/var/lib/angie/angie-config-version.sock`. |
| | N/A | Чтобы запустить Angie, *ANIC* запускает команду `angie`,
которая запускает *главный процесс Angie*. |
| | Сигнал | Чтобы перезагрузить Angie, *ANIC* выполняет команду
`kill -HUP $(cat /run/angie.pid)`, которая проверяет конфигурацию и отправляет
сигнал перезагрузки *главному процессу Angie*. |
| | Сигнал | Чтобы выключить Angie, *ANIC* выполняет команду
`angie -s quit`, которая отправляет сигнал плавного выключения
*главному процессу Angie*. |
| | Файловый ввод-вывод | *Главный процесс Angie* отправляет журнальный
вывод в свои потоки *stdout* и *stderr*, которые собираются средой
выполнения контейнеров. |
| | Файловый ввод-вывод | *Главный процесс Angie* считывает
*TLS-сертификат и ключи*, указанные в конфигурации, при запуске или
перезагрузке. |
| | Файловый ввод-вывод | *Главный процесс Angie* считывает
*конфигурационные файлы* при запуске или во время перезагрузки. |
| | Сигнал | *Главный процесс Angie* управляет жизненным *циклом рабочих
процессов Angie*. Он создает рабочие процессы с новой конфигурацией
и отключает процессы со старой. |
| | Файловый ввод-вывод | *Рабочий процесс Angie* отправляет журнальный
вывод в свои потоки *stdout* и *stderr*, которые собираются средой
выполнения контейнеров. |
| | UDP | *Рабочий процесс Angie* отправляет журналы задержки ответов
HTTP-апстрима в формате Syslog через UNIX-сокет
`/var/lib/angie/angie-syslog.sock` в *ANIC*. В свою очередь,
*ANIC* анализирует и преобразует эти журналы в метрики Prometheus. |
| | HTTP, HTTPS, TCP, UDP | *Клиент* отправляет и получает трафик от любого из
*рабочих процессов Angie* через порты 80 и 443 и любые дополнительные
порты, открытые в [ресурсе GlobalConfiguration](https://angie.software//anic/docs/configuration/globalconfiguration-resource.md#globalconfiguration-resource). |
| | HTTP, HTTPS, TCP, UDP | *Рабочий процесс Angie* отправляет трафик на
*проксируемые серверы* и получает трафик от них. |
| | HTTP | *Администратор* может подключиться к
[stub_status](https://angie.software//angie/docs/configuration/modules/http/http_stub_status.md#id3),
используя порт 8080, через *рабочий процесс Angie*.
#### NOTE
По умолчанию Angie разрешает подключения только от `localhost`. |
## Процесс ANIC
В этом разделе рассматривается архитектура процесса ANIC, включая
следующие вопросы:
- Как ANIC обрабатывает новый ресурс Ingress, созданный пользователем.
- Краткое описание того, как ANIC работает и как он соотносится с
контроллерами Kubernetes.
- Различные компоненты процесса ANIC.
### Обработка нового ресурса Ingress
Ниже рассказано, как ANIC обрабатывает новый ресурс Ingress. Для простоты мы
представляем главный и рабочий процессы Angie в виде единого блока *Angie*.
Также обратите внимание, что ресурсы VirtualServer и VirtualServerRoute
обрабатываются аналогично.
Обработка нового ресурса Ingress включает в себя следующие шаги:
1. *Пользователь* создает новый ресурс Ingress.
2. Процесс ANIC поддерживает *кэш* ресурсов в кластере. *Кэш* содержит
только те ресурсы, которые интересуют ANIC, такие как Ingress. *Кэш*
синхронизируется с API Kubernetes, [отслеживая изменения в
ресурсах](https://kubernetes.io/docs/reference/using-api/api-concepts/#efficient-detection-of-changes).
3. Как только в *кэше* появляется новый ресурс Ingress, он уведомляет
*контур управления* об измененном ресурсе.
4. *Контур управления* получает последнюю версию ресурса Ingress из
*кэша*. Поскольку ресурс Ingress ссылается на другие ресурсы, такие
как секреты TLS, *контур управления* также получает последние версии
любых ресурсов, на которые ведут такие ссылки.
5. *Контур управления* генерирует TLS-сертификаты и ключи из секретов
TLS и записывает их в файловую систему.
6. *Контур управления* генерирует и записывает *конфигурационные файлы*
Angie, которые соответствуют ресурсу Ingress, и записывает их в
файловую систему.
7. *Контур управления* перезагружает *Angie* и ожидает успешной
перезагрузки *Angie*. В ходе перезагрузки:
- *Angie* считывает *TLS-сертификаты и ключи*.
- *Angie* считывает *конфигурационные файлы*.
8. *Контур управления* генерирует событие для ресурса Ingress и
обновляет его статус. Если перезагрузка завершается неудачей, событие
будет содержать сообщение об ошибке.
### ANIC — это контроллер Kubernetes
Основываясь на примере из предыдущего раздела, мы можем обобщить
принципы работы Ingress:
*ANIC постоянно обрабатывает как новые ресурсы, так и изменения в
существующих ресурсах кластера. В результате конфигурация Angie остается
актуальной для ресурсов кластера.*
ANIC является примером [контроллера
Kubernetes](https://kubernetes.io/docs/concepts/architecture/controller/):
ANIC запускает контур управления, который гарантирует, что Angie всегда
будет настроен в соответствии с желаемым состоянием (это ресурсы Ingress
и другие ресурсы).
Желаемое состояние сосредоточено в следующих встроенных и
пользовательских (CR) ресурсах Kubernetes:
- Конфигурация балансировки нагрузки уровня 7:
* Ресурсы Ingress
* Ресурсы [VirtualServer](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserver-and-virtualserverroute-resources) (CR)
* Ресурсы [VirtualServerRoute](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserver-and-virtualserverroute-resources) (CR)
- Политики уровня 7:
* Ресурсы [Policy](https://angie.software//anic/docs/configuration/policy-resource.md#policy-resource) (CR)
- Конфигурация балансировки нагрузки уровня 4:
* Ресурсы [TransportServer](https://angie.software//anic/docs/configuration/transportserver-resource.md#transportserver-resource) (CR)
- Обнаружение сервисов:
* Ресурсы Service
* Ресурсы Endpoint
* Ресурсы Pod
- Конфигурация секретов:
* Ресурсы Secret
- Глобальная конфигурация:
* Ресурс [ConfigMap](https://angie.software//anic/docs/configuration/configmap-resource.md#configmap-resource) (только один ресурс)
* Ресурс [GlobalConfiguration](https://angie.software//anic/docs/configuration/globalconfiguration-resource.md#globalconfiguration-resource) (CR, только один ресурс)
В следующем разделе мы рассмотрим различные компоненты процесса ANIC.
## Компоненты процесса ANIC
В этом разделе мы опишем компоненты процесса ANIC и то, как они
взаимодействуют, включая следующие вопросы:
1. То, как ANIC следит за изменениями ресурсов.
2. Основные компоненты контура управления ANIC.
3. Как эти компоненты обрабатывают изменение ресурса.
4. Несколько дополнительных компонентов, которые имеют решающее значение
для обработки изменений.
ANIC написан на [go](https://golang.org/) и в значительной степени зависит
от [клиента Go для Kubernetes](https://github.com/kubernetes/client-go).
### Кэши ресурсов
В разделе [Обработка нового ресурса Ingress](#processing-new-ingress-resource) мы упоминали, что ANIC поддерживает кэш
ресурсов в кластере, который синхронизируется с API Kubernetes, отслеживая
изменения в ресурсах. Мы также упоминали, что как только кэш обновляется, он
уведомляет контур управления об измененном ресурсе.
Кэш на самом деле представляет собой набор *информеров*. Далее рассказано, как
изменения в ресурсах обрабатываются ANIC.
- Для каждого типа ресурса, который отслеживает ANIC, создается
[информер](https://pkg.go.dev/k8s.io/client-go@v0.21.0/tools/cache#SharedInformer).
*Информер* включает в себя *хранилище*, в котором хранятся ресурсы
этого типа. Чтобы синхронизировать это *хранилище* с последними
версиями ресурсов в кластере, *информер* использует *API-интерфейсы
наблюдения и перечисления Kubernetes* для этого типа ресурсов.
- Когда в кластере происходит изменение (например, создается новый
ресурс), *информер* обновляет свое *хранилище* и вызывает
[обработчики](https://pkg.go.dev/k8s.io/client-go@v0.21.0/tools/cache#ResourceEventHandler)
для этого *информера*.
- ANIC регистрирует обработчики для каждого *информера*. В большинстве
случаев *обработчик* создает запись для затронутого ресурса в
*рабочей очереди*, где элемент рабочей очереди включает тип ресурса,
его пространство имен и название.
- *Рабочая очередь* всегда пытается освободить саму себя: если в ее
начале есть элемент, очередь удалит его и отправит его *контроллеру*,
используя функцию обратного вызова.
- *Контроллер* является основным компонентом в ANIC, который и реализует
контур управления. Описание компонентов см. в разделе [Контур управления](#control-loop). Пока достаточно знать, что для обработки элемента
рабочей очереди *контроллер* получает последнюю версию ресурса из
*хранилища*, перенастраивает *Angie* в соответствии с ресурсом, обновляет
статус ресурса и отправляет событие через *API Kubernetes*.
### Контур управления
В этом разделе рассматриваются основные компоненты ANIC, из которых
состоит контур управления:
- Контроллер:
- Запускает контур управления ANIC.
- Создает экземпляры *информеров*, *обработчиков*, *рабочей очереди*
и дополнительных вспомогательных компонентов.
- Включает метод синхронизации (см. следующий раздел), который
вызывает *рабочая очередь* для обработки измененного ресурса.
- Передает измененные ресурсы в *конфигуратор* для перенастройки
Angie.
- Конфигуратор:
- Генерирует файлы конфигурации Angie, ключи TLS и сертификаты на
основе ресурса Kubernetes.
- Использует *менеджер* для записи сгенерированных файлов и
перезагрузки Angie.
- Менеджер:
- Управляет жизненным циклом Angie (запуск, перезагрузка, завершение
работы).
- Управляет конфигурационными файлами, ключами TLS и сертификатами.
#### Вспомогательные компоненты
Есть два дополнительных вспомогательных компонента, имеющих решающее
значение для обработки изменений: *Конфигурация* и *Локальное хранилище
секретов*.
##### Конфигурация
Конфигурация содержит последнее допустимое состояние ресурсов
конфигурации балансировки нагрузки ANIC, как то: ресурсы Ingress,
VirtualServer, VirtualServerRoute, TransportServer и
GlobalConfiguration.
*Конфигурация* поддерживает операции добавления (для добавления или
обновления) и удаления ресурсов. Когда вы добавляете, обновляете или
удаляете ресурс в конфигурации, она делает следующее:
1. Проверяет объект (в случае добавления или обновления).
2. Вычисляет изменения в затронутых ресурсах, которые необходимо
передать в конфигурацию Angie, возвращая изменения вызывающей
стороне.
Например, когда вы добавляете новый ресурс Ingress, *конфигурация*
возвращает изменение, требующее от ANIC добавления конфигурации для
этого ресурса в конфигурационные файлы Angie. Другой пример: если вы
сделаете существующий ресурс Ingress недействительным, *конфигурация*
вернет изменение, требующее от ANIC удалить конфигурацию для этого
ресурса из конфигурационных файлов Angie.
Кроме того, *конфигурация* гарантирует, что только один ресурс Ingress,
VirtualServer или TransportServer (TLS Passthrough) содержит
определенный хост (например, `mysite.example.com`), и только один ресурс
TransportServer (TCP, UDP) содержит определенный прослушиватель
(например, порт `53` для UDP). Это гарантирует, что в конфигурации Angie
не произойдет коллизий между хостом и прослушивателем.
В конечном счете, ANIC гарантирует, что конфигурация Angie в файловой
системе отражает состояние объектов в *конфигурации* в любой момент
времени.
##### Локальное хранилище секретов
Локальное хранилище секретов содержит допустимые секретные ресурсы и
синхронизирует с ними соответствующие файлы в файловой системе. Секреты
используются для хранения сертификатов и ключей TLS (тип
`kubernetes.io/tls`), центров сертификации, а также клиентских секретов провайдера OIDC.
Когда *контроллер* обрабатывает изменение в ресурсе конфигурации, таком
как Ingress, он создает расширенную версию ресурса, которая включает
зависимости, такие как секреты, необходимые для генерации конфигурации
Angie. *Локальное хранилище секретов* позволяет *контроллеру* получить
ссылку на файловую систему для секрета с помощью ключа секрета
(`пространство имен/имя`).
## Перезагрузка Angie
В следующем разделе рассматривается перезагрузка Angie в целом и, в
частности, ее реализация в ANIC.
### Перезагрузка в целом
Перезагрузка Angie необходима для применения новой конфигурации и
включает в себя следующие действия:
1. Администратор отправляет сигнал HUP (зависание) главному процессу
Angie, чтобы запустить перезагрузку.
2. Главный процесс завершает работу рабочих процессов со старой
конфигурацией и запускает рабочие процессы с новой конфигурацией.
3. Администратор проверяет, что перезагрузка успешно завершена.
#### NOTE
Обратитесь к [документации Angie](https://angie.software//angie/docs/configuration/runtime.md#runtime) для получения более подробной
информации о перезагрузке.
#### Как выполнить перезагрузку
Двоичный файл Angie (`angie`) поддерживает операцию перезагрузки с
параметром `-s reload`. Когда вы используете эту опцию:
1. Процесс проверяет новую конфигурацию Angie и завершает работу, если
она недействительна, выводя сообщения об ошибках в stderr.
2. Он посылает сигнал HUP главному процессу Angie и завершает работу.
В качестве альтернативы вы можете отправить сигнал HUP непосредственно
главному процессу Angie.
#### Как убедиться в успехе перезагрузки
Команда `kill -HUP $(cat /run/angie.pid)` не дожидается завершения перезагрузки Angie.
В результате именно администратор несет ответственность за подтверждение
ее успешности. Есть несколько вариантов:
- Проверьте, создал ли главный процесс новые рабочие процессы.
Например, запустив `ps` или прочитав файловую систему `/proc`.
- Отправьте HTTP-запрос в Angie, и если ответит новый рабочий процесс,
вы будете знать, что Angie успешно перезагрузился.
#### NOTE
Для этого требуется дополнительная настройка Angie.
Перезагрузка занимает некое время, обычно не менее 200 мс. Это время зависит
от размера конфигурации, количества TLS-сертификатов и ключей,
включенных модулей, подробностей конфигурации и доступных ресурсов ЦП.
#### Потенциальные проблемы
В большинстве случаев, если команда `kill -HUP $(cat /run/angie.pid)` завершается
успешно, перезагрузка также будет успешной. В редких случаях
перезагрузка завершается неудачей, и главный процесс Angie добавит
сообщение об ошибке в журнал ошибок. Например:
```console
2022/07/09 00:56:42 [emerg] 1353#1353: limit_req "one" uses the
"$remote_addr" key while previously it used the "$binary_remote_addr" key
```
Операция выполняется плавно; перезагрузка не приводит к потере трафика Angie.
Однако частые перезагрузки могут привести к повышенной загрузке памяти и
потенциальной остановке Angie с ошибкой OOM (нехватка памяти), что приведет к
потере трафика. Это может произойти, если вы 1) проксируете трафик, который
использует долгоживущие соединения (например, Websockets, gRPC) и 2) часто
перезагружаете конфигурацию. В этом случае вы можете столкнуться с несколькими
поколениями завершающих работу рабочих процессов Angie (старые рабочие процессы
Angie не будут завершаться до тех пор, пока все соединения не будут прерваны
либо клиентами, либо проксируемыми серверами, если только вы не настроите
[worker_shutdown_timeout](https://angie.software//angie/docs/configuration/modules/core.md#worker-shutdown-timeout), что заставит старые рабочие процессы завершать
работу после тайм-аута). В конечном счете все эти рабочие процессы могут
исчерпать доступную системную память.
Поскольку как старые, так и новый рабочие процессы Angie сосуществуют во время
перезагрузки, она может привести к резкому увеличению использования памяти
вплоть до двукратного. Из-за нехватки доступной памяти главный процесс Angie
может лишиться возможности создавать новые рабочие процессы.
# https://angie.software/anic/docs/installation.md
# Установка
В этом разделе описаны доступные способы установки ANIC, а также миграция с Ingress-NGINX Controller на ANIC.
> [Установка с помощью Helm](https://angie.software//anic/docs/installation/installation-with-helm.md#installation-with-helm)
> [Получение лицензии](https://angie.software//anic/docs/installation/licensing.md#licensing)
> [Установка и настройка для Яндекс.Облака](https://angie.software//anic/docs/installation/installation-in-YC.md#installation-in-yc)
> [Миграция с Ingress-NGINX Controller на ANIC](https://angie.software//anic/docs/installation/migration.md#migration-to-anic)
# https://angie.software/anic/docs/installation/installation-with-helm.md
# Установка с помощью Helm
Angie Ingress Controller (ANIC) разворачивается в
кластере Kubernetes с помощью Helm.
Программные требования:
- Kubernetes 1.22+
- Helm 3.0+
Поддерживаемые дистрибутивы:
| Название | Версии | Архитектуры |
|--------------|-----------------|---------------|
| Alpine Linux | `3.21` | x86_64, ARM64 |
| Debian | `11` "Bullseye" | x86_64, ARM64 |
| ALT Linux | `10` | x86_64, ARM64 |
## Получение доступа к образу ANIC
1. Авторизуйтесь в Docker Registry, чтобы получить доступ к образу ANIC:
```console
$ docker login -u= -p= anic.docker.angie.software
```
После успешной авторизации информация о доступе будет сохранена в файле `~/.docker/config.json`.
2. Создайте секрет для Kubernetes, используя файл Docker-конфигурации:
```console
$ kubectl create secret generic regcred \
--from-file=.dockerconfigjson=$HOME/.docker/config.json \
--type=kubernetes.io/dockerconfigjson
```
Секрет `regcred` будет использоваться для доступа к приватным образам в Kubernetes.
## Cкачаивание образа ANIC
Cкачайте образ ANIC и перенесите его в свой личный репозиторий, для этого:
1. Загрузите образ ANIC:
```console
$ docker pull anic.docker.angie.software/anic:latest
```
2. Переименуйте образ:
```console
$ docker tag anic.docker.angie.software/anic:latest <ваш_репозиторий>/<образ_anic>
```
3. Отправьте переименованный образ в свой репозиторий:
```console
$ docker push <ваш_репозиторий>/<образ_anic>
```
4. В файле `values.yaml` обновите поле `controller.image.repository` соответственно.
## Подключение лицензии
Подключите лицензию для ANIC, следуя [инструкции](https://angie.software//anic/docs/installation/licensing.md#licensing).
## Получение и настройка Helm-чарта
1. Склонируйте Helm-чарт из [репозитория Angie Software](https://git.angie.software/web-server/anic-helm-charts/).
Доступ к репозиторию можно получить, обратившись на [info@wbsrv.ru](mailto:info@wbsrv.ru).
```console
$ git clone https://git.angie.software/web-server/anic-helm-charts.git
```
2. Отредактируйте файл `values.yaml`, указав имя секрета, созданного
для доступа к образам:
```yaml
imagePullSecretName: "regcred"
```
3. Соберите и установите Helm-чарт:
```console
$ helm install <имя_релиза> <путь_до_чарта>
```
Helm cгенерирует манифесты Kubernetes на основе шаблонов (`templates/`)
и значений (`values.yaml`), а затем установит их в кластере.
#### NOTE
По умолчанию для ANIC требуется несколько CRD (определений пользовательских
ресурсов), установленных в кластере.
Helm устанавливает их автоматически.
Если не установить CRD, поды ANIC не будут готовы (`Ready`).
Если вы не используете пользовательские ресурсы, для которых требуются
CRD (что соответствует параметру `controller.enableCustomResources`,
установленному как `false`), установку CRD можно пропустить, указав
в команде `helm install` параметр `--skip-crds`.
## Обновление CRD
Чтобы обновить CRD, скачайте исходные файлы Helm-чарта,
а затем выполните команду:
```console
$ kubectl apply -f crds/
```
#### NOTE
Может появиться следующее предупреждение, но его можно проигнорировать:
```none
Warning: kubectl apply should be used on resource created by either
kubectl create --save-config or kubectl apply
```
## Удаление CRD
Чтобы удалить CRD, скачайте исходные файлы Helm-чарта,
а затем выполните команду:
```console
$ kubectl delete -f crds/
```
#### NOTE
Эта команда удалит все соответствующие CRD в вашем
кластере во всех пространствах имен. Убедитесь, что в кластере нет
пользовательских ресурсов, которые вы хотите сохранить, и не запущены другие
экземпляры ANIC.
## Конфигурация
Ниже перечислены настраиваемые параметры Helm-чарта Ingress
Controller и их значения по умолчанию.
### `controller.name`
Имя daemonset или deployment ANIC.
По умолчанию: создается автоматически
### `controller.kind`
Тип установки ANIC - deployment или daemonset.
По умолчанию: deployment
### `controller.annotations`
Позволяет устанавливать `аннотации` для deployment или daemonset.
По умолчанию: {}
### `controller.angiePro`
Развертывает ANIC для Angie PRO.
По умолчанию: false
### `controller.angieDashboard.enable`
Включает Angie Dashboard (status endpoint для получения информации о состоянии Angie).
Соответствует аргументу командной строки `-angie-dashboard`.
По умолчанию: false
### `controller.angieDashboard.port`
Задает порт для Angie Dashboard.
Соответствует аргументу командной строки `-angie-dashboard-port`.
По умолчанию: 8082
### `controller.angieDashboard.allowCidrs`
Добавляет блоки IP/CIDR в список разрешенных для Angie Dashboard.
Соответствует аргументу командной строки `-angie-dashboard-allow-cidrs`.
Несколько IP или CIDR разделяются запятыми.
По умолчанию: 127.0.0.1,::1
### `controller.angieStatusPrometheus.enable`
Включает выдачу [статистики Angie в формате Prometheus](https://angie.software/configuration/modules/http_prometheus/).
Соответствует аргументу командной строки `-angie-status-prometheus`.
По умолчанию: true
### `controller.angieStatusPrometheus.port`
Задает порт, на котором доступна [статистика Angie в формате Prometheus](https://angie.software/configuration/modules/http_prometheus/).
Формат: `[1024 - 65535]`.
Соответствует аргументу командной строки `-angie-status-prometheus-port`.
По умолчанию: 8083
### `controller.angieStatusPrometheus.allowCidrs`
Добавляет блоки IP/CIDR в список разрешений для
[статистики Angie в формате Prometheus](https://angie.software/configuration/modules/http_prometheus/).
Соответствует аргументу командной строки `-angie-status-prometheus-allow-cidrs`.
Несколько IP или CIDR разделяются запятыми.
По умолчанию: 127.0.0.1,::1
### `controller.angieStatusPrometheus.path`
Позволяет менять путь для публикации [статистики Angie в формате Prometheus](https://angie.software/configuration/modules/http_prometheus/).
Соответствует аргументу командной строки `-angie-status-prometheus-path`.
По умолчанию: /p8s
### `controller.angieStatusPrometheus.service.create`
Создает сервис ClusterIP для предоставления метрик веб-сервера Angie.
По умолчанию: false
### `controller.angieStatusPrometheus.service.labels`
Задает лейблы для сервиса ClusterIP.
По умолчанию: service: "anic-webserver-metrics"
### `controller.angieStatusPrometheus.serviceMonitor.create`
Создает ServiceMonitor для метрик веб-сервера Angie.
По умолчанию: false
### `controller.angieStatusPrometheus.serviceMonitor.labels`
Задает лейблы для сервиса ServiceMonitor.
По умолчанию: Нет
### `controller.reloadTimeout`
Время ожидания в миллисекундах, в течение которого ANIC
будет ожидать успешной перезагрузки Angie после изменения или при
начальном запуске.
По умолчанию: 60000
### `controller.hostNetwork`
Позволяет подам ANIC использовать сетевое пространство
имен хоста.
По умолчанию: false
### `controller.dnsPolicy`
Политика DNS для подов ANIC.
По умолчанию: ClusterFirst
### `controller.debug`
Включает отладку для Angie. Требуется задать значение `error-log-level:
debug` в ConfigMap через `controller.config.entries`.
По умолчанию: false
### `controller.logLevel`
Уровень ведения журнала ANIC.
По умолчанию: 1
### `controller.image.digest`
Дайджест образа ANIC.
По умолчанию: Нет
### `controller.image.repository`
Репозиторий образов ANIC.
По умолчанию: myregistry.host.ru/angie-ingress
### `controller.image.tag`
Тег образа ANIC.
По умолчанию:
### `controller.image.pullPolicy`
Политика скачивания образа ANIC.
По умолчанию: IfNotPresent
### `controller.lifecycle`
Жизненный цикл подов ANIC.
По умолчанию: {}
### `controller.customConfigMap`
Имя пользовательской ConfigMap, используемой ANIC. Если
имя задано, то конфигурация по умолчанию игнорируется.
По умолчанию: ""
### `controller.config.name`
Имя ConfigMap, используемой ANIC.
По умолчанию: создается автоматически
### `controller.config.annotations`
Аннотации к ConfigMap в ANIC.
По умолчанию: {}
### `controller.config.entries`
Записи в ConfigMap для настройки конфигурации Angie.
По умолчанию: {}
### `controller.customPorts`
Список пользовательских портов, которые должны быть доступны в поде
ANIC. Следует обычному синтаксису yaml Kubernetes для
контейнерных портов.
По умолчанию: []
### `controller.defaultTLS.cert`
Сертификат TLS в кодировке `Base64` для сервера HTTPS по умолчанию.
#### NOTE
Рекомендуется указать свой собственный сертификат. Альтернативное
решение: полный пропуск секрета сервера по умолчанию приведет к тому,
что Angie будет по умолчанию отклонять TLS-подключения к серверу.
По умолчанию: Нет
### `controller.defaultTLS.key`
Ключ TLS в кодировке `Base64` для сервера HTTPS по умолчанию.
#### NOTE
Рекомендуется указать свой собственный ключ. Альтернативное решение:
полный пропуск секрета сервера по умолчанию приведет к тому, что
Angie будет по умолчанию отклонять TLS-подключения к серверу.
По умолчанию: Нет
### `controller.defaultTLS.secret`
Секрет с сертификатом TLS и ключом для сервера HTTPS по умолчанию.
Значение должно соответствовать следующему формату: `<пространство имен>/<имя>`.
Используется в качестве альтернативы указанию сертификата
и ключа с помощью параметров `controller.defaultTLS.cert` и
`controller.defaultTLS.key`.
#### NOTE
Альтернативное решение: полный пропуск секрета сервера по умолчанию
приведет к тому, что Angie будет по умолчанию отклонять TLS-подключения
к серверу.
По умолчанию: Нет
### `controller.wildcardTLS.cert`
Сертификат TLS в кодировке `Base64` для каждого узла Ingress или
VirtualServer, у которого включен TLS, но не указан секрет. Если
параметр не задан, Angie прервет любую попытку установить TLS-соединение
для таких узлов Ingress или VirtualServer.
По умолчанию: Нет
### `controller.wildcardTLS.key`
Ключ TLS в кодировке `Base64` для каждого узла Ingress или VirtualServer,
у которого включен TLS, но не указан секрет. Если параметр не задан,
Angie прервет любую попытку установить TLS-соединение для таких узлов
Ingress или VirtualServer.
По умолчанию: Нет
### `controller.wildcardTLS.secret`
Секрет с сертификатом TLS и ключом для каждого узла Ingress или
VirtualServer, у которого включен TLS, но не указан секрет. Значение
должно соответствовать следующему формату: `<пространство имен>/<имя>`.
Используется в качестве альтернативы указанию сертификата и ключа с
помощью параметров `controller.wildcardTLS.cert` и
`controller.wildcardTLS.key`.
По умолчанию: Нет
### `controller.nodeSelector`
Селектор узлов для назначения подов ANIC.
По умолчанию: {}
### `controller.terminationGracePeriodSeconds`
Период плавного завершения работы пода ANIC.
По умолчанию: 30
### `controller.tolerations`
Допуски подов ANIC (tolerations).
По умолчанию: []
### `controller.affinity`
Привязка подов ANIC (affinity).
По умолчанию: {}
### `controller.topologySpreadConstraints`
Ограничения на распространение топологии подов ANIC.
По умолчанию: {}
### `controller.env`
Дополнительные переменные окружения, которые должны быть установлены на
подах ANIC.
По умолчанию: []
### `controller.volumes`
Тома подов ANIC.
По умолчанию: []
### `controller.volumeMounts`
Точки подключения томов подов ANIC.
По умолчанию: []
### `controller.initContainers`
Значение initContainers для подов ANIC.
По умолчанию: []
### `controller.extraContainers`
Дополнительные контейнеры (например, сайдкар) для подов Ingress
Controller.
По умолчанию: []
### `controller.resources`
Ресурсы подов ANIC.
По умолчанию: requests: cpu=100m,memory=128Mi
### `controller.replicaCount`
Количество реплик deployment ANIC.
По умолчанию: 1
### `controller.ingressClass`
Класс ANIC. Должен быть развернут ресурс IngressClass с
именем, тождественным этому классу. В противном случае ANIC
не запустится. ANIC обрабатывает только те
ресурсы, которые принадлежат его классу, т. е. их ресурс поля
"ingressClassName" совпадает с классом. ANIC обрабатывает
все ресурсы VirtualServer, VirtualServerRoute и TransportServer, которые
не имеют поля "ingressClassName", во всех версиях Kubernetes.
По умолчанию: angie
### `controller.setAsDefaultIngress`
Новым Ingress без указанного поля "ingressClassName" будет присвоен
класс, указанный в controller.ingressClass.
По умолчанию: false
### `controller.watchNamespace`
Разделенный запятыми список пространств имен, за ресурсами которых
должен следить ANIC. По умолчанию ANIC
отслеживает все пространства имен. Взаимоисключающие с
`controller.watchNamespaceLabel`. Обратите внимание, что при настройке
нескольких пространств имен с использованием опции Helm cli `--set`
строка должна быть заключена в двойные кавычки, а запятые экранированы с
помощью обратной косой черты - например, `--set
controller.watchNamespace="default\,anic"`.
По умолчанию: ""
### `controller.watchNamespaceLabel`
Настраивает в ANIC просмотр только пространств имен с
меткой foo=bar. По умолчанию ANIC отслеживает все
пространства имен. Взаимоисключающая с `controller.watchNamespace`
настройка.
По умолчанию: ""
### `controller.watchSecretNamespace`
Разделенный запятыми список пространств имен, за которыми Ingress
Controller должен следить в поисках ресурсов типа Secret. Если этот
параметр не настроен, ANIC отслеживает одни и те же
пространства имен в поисках всех ресурсов. См. также
`controller.watchNamespace` и `controller.watchNamespaceLabel`. Обратите
внимание, что при настройке нескольких пространств имен с использованием
опции Helm cli `--set` строка должна быть заключена в двойные кавычки, а
запятые экранированы с помощью обратной косой черты - например, `--set
controller.watchSecretNamespace="default\,angie-ingress"`.
По умолчанию: ""
### `controller.enableCustomResources`
Включает пользовательские ресурсы.
По умолчанию: true
### `controller.enableTLSPassthrough`
Включает передачу данных по протоколу TLS на порту 443. Требуется
controller.enableCustomResources.
По умолчанию: false
### `controller.enableCertManager`
Включает автоматическое управление сертификатами x509 для ресурсов
виртуального сервера с помощью cert-manager (cert-manager.io). Требуется
`controller.enableCustomResources`.
По умолчанию: false
### `controller.enableExternalDNS`
Включает интеграцию с ExternalDNS для настройки общедоступных записей
DNS у ресурсов VirtualServer с использованием [ExternalDNS](https://github.com/kubernetes-sigs/external-dns). Требуется
controller.enableCustomResources.
По умолчанию: false
### `controller.globalConfiguration.create`
Создает пользовательский ресурс GlobalConfiguration. Требуется
controller.enableCustomResources.
По умолчанию: false
### `controller.globalConfiguration.spec`
Спецификация GlobalConfiguration для определения параметров глобальной
конфигурации ANIC.
По умолчанию: {}
### `controller.enableSnippets`
Включает пользовательские фрагменты конфигурации Angie в ресурсах
Ingress, VirtualServer, VirtualServerRoute и TransportServer.
По умолчанию: false
### `controller.healthStatus`
Добавляет местоположение "/angie-health" на сервер по умолчанию.
Местоположение отвечает кодом статуса 200 на любой запрос. Это полезно
для внешней проверки работоспособности ANIC.
По умолчанию: false
### `controller.healthStatusURI`
Задает URI местоположения состояния работоспособности на сервере по
умолчанию. Требуется `controller.HealthStatus`.
По умолчанию: "/angie-health"
### `controller.angieStatus.enable`
Включает в Angie API.
По умолчанию: true
### `controller.angieStatus.port`
Задает порт, на котором доступен Angie API.
По умолчанию: 8080
### `controller.angieStatus.allowCidrs`
Добавляет блоки IP или CIDR в список разрешенных для Angie API.
Несколько IP или CIDR разделяются запятыми.
По умолчанию: 127.0.0.1,::1
### `controller.priorityClassName`
Класс приоритета подов ANIC.
По умолчанию: Нет
### `controller.service.create`
Создает сервис для предоставления доступа к подам ANIC.
По умолчанию: true
### `controller.service.type`
Тип сервиса, который необходимо создать для ANIC.
По умолчанию: LoadBalancer
### `controller.service.externalTrafficPolicy`
Внешняя политика трафика сервиса. Значение Local сохраняет исходный
IP-адрес клиента.
По умолчанию: Local
### `controller.service.annotations`
Аннотации сервиса ANIC.
По умолчанию: {}
### `controller.service.extraLabels`
Экстра-метки сервиса.
По умолчанию: {}
### `controller.service.loadBalancerIP`
Статический IP-адрес для балансировщика нагрузки. Для
`controller.service.type` должно быть установлено значение
`LoadBalancer`. Поставщик облачных услуг должен поддерживать эту
функцию.
По умолчанию: ""
### `controller.service.externalIPs`
Список внешних IP-адресов для сервиса ANIC.
По умолчанию: []
### `controller.service.loadBalancerSourceRanges`
Диапазоны IP-адресов (CIDR), которым разрешен доступ к балансировщику
нагрузки. Для `controller.service.type` должно быть установлено значение
`LoadBalancer`. Поставщик облачных услуг должен поддерживать эту
функцию.
По умолчанию: []
### `controller.service.name`
Имя сервиса.
По умолчанию: создается автоматически
### `controller.service.customPorts`
Список пользовательских портов, которые будут доступны через сервис
ANIC. Следует обычному синтаксису yaml Kubernetes для
портов сервиса.
По умолчанию: []
### `controller.service.httpPort.enable`
Включает HTTP-порт для сервиса ANIC.
По умолчанию: true
### `controller.service.httpPort.port`
HTTP-порт сервиса ANIC.
По умолчанию: 80
### `controller.service.httpPort.nodePort`
Пользовательский NodePort для HTTP-порта. Для `controller.service.type`
должно быть установлено значение `NodePort`.
По умолчанию: ""
### `controller.service.httpPort.targetPort`
Целевое значение HTTP-порта сервиса ANIC.
По умолчанию: 80
### `controller.service.httpsPort.enable`
Включает порт HTTPS для сервиса ANIC.
По умолчанию: true
### `controller.service.httpsPort.port`
HTTPS-порт сервиса ANIC.
По умолчанию: 443
### `controller.service.httpsPort.nodePort`
Пользовательский NodePort для HTTPS-порта. Для `controller.service.type`
должно быть установлено значение `NodePort`.
По умолчанию: ""
### `controller.service.httpsPort.targetPort`
Целевой порт HTTPS-порта сервиса ANIC.
443
### `controller.serviceAccount.annotations`
Аннотации учетной записи сервиса ANIC.
По умолчанию: {}
### `controller.serviceAccount.name`
Имя учетной записи сервиса подов ANIC. Используется для
RBAC.
По умолчанию: создается автоматически
### `controller.serviceAccount.imagePullSecretName`
Имя секретного файла, содержащего учетные данные реестра Docker. Секрет
должен находиться в том же пространстве имен, что и релиз Helm.
По умолчанию: ""
### `controller.reportIngressStatus.enable`
Добавляет в поле адреса в статусе ресурсов Ingress внешний адрес Ingress
Controller. Нужно также указать источник внешнего адреса через внешнюю
службу через `controller.reportIngressStatus.ExternalService`, либо
через `controller.reportIngressStatus.ingressLink,` либо через запись
`external-status-address` в ConfigMap через `controller.config.entries`.
#### NOTE
Значение `controller.config.entries.external-status-address` имеет
приоритет над остальными.
По умолчанию: true
### `controller.reportIngressStatus.externalService`
Указывает имя сервиса с типом LoadBalancer, через который Ingress
Controller будет доступен извне. Внешний адрес сервиса используется для
отчетов о состоянии ресурсов Ingress, VirtualServer и
VirtualServerRoute. Значение `controller.reportIngressStatus.enable`
должно быть задано как `true`. Значение по умолчанию создается
автоматически и включается, когда `controller.service.create` имеет
значение `true`, а `controller.service.type` - значение `LoadBalancer`.
По умолчанию: создается автоматически
### `controller.reportIngressStatus.ingressLink`
Указывает имя ресурса IngressLink, который предоставляет доступ к подам
ANIC через систему BIG-IP. IP-адрес системы BIG-IP
используется для отчетов о состоянии ресурсов Ingress, VirtualServer и
VirtualServerRoute. Значение `controller.reportIngressStatus.enable`
должно быть задано как `true`.
По умолчанию: ""
### `controller.reportIngressStatus.enableLeaderElection`
Включает выбор лидера, чтобы избежать ситуации, когда несколько реплик
контроллера сообщают о состоянии ресурсов Ingress. Значение
`controller.reportIngressStatus.enable` должно быть задано как `true`.
По умолчанию: `true`
### `controller.reportIngressStatus.leaderElectionLockName`
Указывает имя ConfigMap в том же пространстве имен, что и контроллер,
которое используется для блокировки выбора лидера. Значение
controller.reportIngressStatus.enableLeaderElection должно быть задано
как `true`.
По умолчанию: создается автоматически
### `controller.reportIngressStatus.annotations`
Аннотации к конфигурационной карте выборов лидера.
По умолчанию: {}
### `controller.pod.annotations`
Аннотации пода ANIC.
По умолчанию: {}
### `controller.pod.extraLabels`
Дополнительные экстра-метки для пода ANIC.
По умолчанию: {}
### `controller.readyStatus.enable`
Включает конечную точку готовности `"/angie-ready"`. Конечная точка
возвращает код успешного завершения, если Angie загрузил всю
конфигурацию после запуска. Этим также настраивается проверка готовности
для подов ANIC, которая использует конечную точку
готовности.
По умолчанию: `true`
### `controller.readyStatus.port`
HTTP-порт для конечной точки готовности.
По умолчанию: `8081`
### `controller.readyStatus.initialDelaySeconds`
Число секунд с запуска пода ANIC до инициирования проверки
готовности.
По умолчанию: `0`
### `controller.enableLatencyMetrics`
Включает сбор метрик задержки для апстримов. Требуется
`prometheus.create`.
По умолчанию: `false`
### `controller.minReadySeconds`
Задает минимальное количество секунд, в течение которых вновь созданный
под должен прийти в готовое состояние без сбоя какого-либо из
контейнеров, чтобы считаться доступным; документацию см. [здесь](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#min-ready-seconds).
По умолчанию: `0`
### `controller.autoscaling.enabled`
Включает HorizontalPodAutoscaling.
По умолчанию: `false`
### `controller.autoscaling.annotations`
Аннотации HorizontalPodAutoscaler для ANIC.
По умолчанию: {}
### `controller.autoscaling.minReplicas`
Минимальное число реплик для HPA.
По умолчанию: `1`
### `controller.autoscaling.maxReplicas`
Максимальное число реплик для HPA.
По умолчанию: `3`
### `controller.autoscaling.targetCPUUtilizationPercentage`
Целевой процент загрузки ЦП.
По умолчанию: `50`
### `controller.autoscaling.targetMemoryUtilizationPercentage`
Целевой процент использования памяти.
По умолчанию: `50`
### `controller.podDisruptionBudget.enabled`
Включает PodDisruptionBudget.
По умолчанию: `false`
### `controller.podDisruptionBudget.annotations`
Аннотации к бюджету сбоев пода ANIC.
По умолчанию: {}
### `controller.podDisruptionBudget.minAvailable`
Количество подов ANIC, которые должны быть доступны.
Взаимоисключающая с `maxUnavailable`` настройка.
По умолчанию: `0`
### `controller.podDisruptionBudget.maxUnavailable`
Количество подов ANIC, которые могут быть недоступны.
Взаимоисключающая с `minAvailable` настройка.
По умолчанию: 0
### `controller.strategy`
Задает стратегию замены старых подов новыми. Документация по [стратегии
обновления развертывания](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy)
и [стратегии обновления daemonset](https://kubernetes.io/docs/tasks/manage-daemon/update-daemon-set/#daemonset-update-strategy)
По умолчанию: {}
### `controller.disableIPV6`
В явной форме отключает прослушиватели IPV6 для узлов, которые не
поддерживают стек IPV6.
По умолчанию: `false`
### `controller.readOnlyRootFilesystem`
Настраивает корневую файловую систему как доступную только для чтения и
добавляет тома для временных данных.
По умолчанию: `false`
### `rbac.create`
Настраивает RBAC.
По умолчанию: `true`
### `prometheus.create`
Публикует метрики ANIC в формате Prometheus.
По умолчанию: `true`
### `prometheus.port`
Настраивает порт для получения метрик.
По умолчанию: `9113`
### `prometheus.scheme`
Настраивает схему HTTP, используемую для подключений к конечной точке
Prometheus.
По умолчанию: `http`
### `prometheus.secret`
Пространство имен или имя TLS-секрета Kubernetes. Если секрет указан, он
используется для защиты конечной точки Prometheus с помощью
TLS-соединений.
По умолчанию: ""
### `prometheus.service.create`
Создает сервис ClusterIP для метрик ANIC.
По умолчанию: `false`
### `prometheus.service.labels`
Задает лейблы для сервиса ClusterIP.
По умолчанию: service: "anic-prometheus-service"
### `prometheus.serviceMonitor.create`
Создает ServiceMonitor для метрик ANIC.
По умолчанию: `false`
### `prometheus.serviceMonitor.labels`
Задает лейблы для сервиса ServiceMonitor.
По умолчанию: Нет
# https://angie.software/anic/docs/installation/install.md
# Установка с помощью манифестов
## Предварительные требования
Необходим доступ к Docker-образу в нашем репозитории:
```none
anic.docker.angie.software/
```
Для текущей версии доступны следующие образы:
```none
anic.docker.angie.software/anic:0.7.5-alpine
anic.docker.angie.software/anic:0.7.5-alpine-debian
anic.docker.angie.software/anic:0.7.5-altlinux
```
За доступом обращайтесь на [info@wbsrv.ru](mailto:info@wbsrv.ru).
## Настройка RBAC
1. Создайте пространство имен и сервисный аккаунт для ANIC:
```yaml
$ kubectl apply -f - <
- `DaemonSet`: используйте этот тип, если планируете развертывать ANIC на
каждом узле кластера или подмножестве узлов.
### Пример DaemonSet
```yaml
$ kubectl apply -f - <
# Подключение лицензии
Перед [установкой ANIC](https://angie.software//anic/docs/installation/installation-with-helm.md#installation-with-helm) необходимо подключить лицензию с помощью файла `licence.pem`.
Файл `licence.pem` содержит лицензионный ключ и подтверждает право на использование ANIC.
Получить его можно, обратившись в техническую поддержку или скачав в личном кабинете.
Чтобы подключить лицензию, выполните следующие шаги:
1. Создайте секрет с лицензионным ключом:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: angie-pro-secret
namespace: default
data:
angiePro.license:
```
Здесь `` - лицензионный ключ, закодированный в `Base64`, из файла `licence.pem`.
Пример конвертации в Linux:
```bash
$ cat license.pem | base64 -w0
```
Пример вывода:
```text
LS0tLS1CRUdJTiBMSUNFTlNFLS0tLS0KZDI5eWEyVnl........................1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=
```
2. Добавьте секрет в файл `values.yaml`.
Для этого найдите в `values.yaml` параметр `angieProLicense` и добавьте для него значение `<пространство имен/имя секрета>`, например:
```yaml
angieProLicense: "default/angie-pro-secret"
```
Далее продолжите установку ANIC [по инструкции](https://angie.software//anic/docs/installation/installation-with-helm.md#installation-with-helm).
# https://angie.software/anic/docs/installation/installation-in-YC.md
# Установка и настройка для Яндекс.Облака
В этом разделе описана установка и настройка ANIC в качестве Ingress для Яндекс.Облака.
## Настройка локальной рабочей среды для работы с Kubernetes и Яндекс.Облаком
Пример для Ubuntu 24/04.
1. Скачайте и установите CLI (YC) для управления ресурсами в Яндекс.Облаке:
```console
$ curl -sSL https://storage.yandexcloud.net/yandexcloud-yc/install.sh | bash
$ yc init
```
Запустится процесс настройки CLI, где потребуется ввести токен для доступа в Яндекс.Облако.
Токен можно получить по ссылке [https://oauth.yandex.ru/verification_code](https://oauth.yandex.ru/verification_code).
2. Добавьте параметры подключения к Kubernetes-кластеру (например, `otus`) в файл `~/.kube/config` и подключитесь к кластеру:
```console
$ yc managed-kubernetes cluster get-credentials otus --external
```
3. Проверьте конфигурацию кластера, ноды и доступные сервисы:
```console
$ kubectl config view
$ kubectl get nodes
$ kubectl get svc
```
## Получение доступа к образу ANIC
1. Создайте Docker-секрет.
Выполните авторизацию в Docker Registry, чтобы получить доступ к образу:
```console
$ docker login -u= -p= anic.docker.angie.software
```
После успешной авторизации информация о доступе будет сохранена в файле `~/.docker/config.json`.
2. Создайте секрет для Kubernetes, используя файл Docker-конфигурации:
```console
$ kubectl create secret generic regcred \
--from-file=.dockerconfigjson=$HOME/.docker/config.json \
--type=kubernetes.io/dockerconfigjson
```
Секрет `regcred` будет использоваться для доступа к приватным образам в Kubernetes.
## Получение и настройка Helm-чартов
1. Склонируйте Helm-чарты из репозитория:
```none
$ git clone https://git.angie.software/web-server/anic-helm-charts.git
$ cd anic-helm-charts/anic/
```
2. Отредактируйте `values.yaml`. Укажите имя созданного секрета
для доступа к образам и включите поддержку менеджера сертификатов:
```yaml
...
imagePullSecretName: "regcred"
...
enableCertManager: true
...
```
3. Соберите и установите чарт:
```none
$ helm install anic .
```
4. Обновите чарт:
```none
$ helm upgrade anic .
```
## Запуск менеджера сертификатов
1. Установите `cert-manager` для управления сертификатами.
Работа тестировалась на примере версии 1.12.1:
```console
$ kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.12.1/cert-manager.yaml
```
2. Убедитесь, что три пода `cert-manager` находятся в состоянии `running` с готовностью 1/1:
```console
$ kubectl get pods -n cert-manager --watch
```
3. Создайте объект ClusterIssuer для выпуска сертификатов:
### http01-clusterissuer.yaml
```yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: http01-clusterissuer
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: test@test.ru
privateKeySecretRef:
name: http01-clusterissuer-secret
solvers:
- http01:
ingress:
class: angie
```
В этом примере cert-manager настроен для автоматической выдачи сертификатов от Let's Encrypt с помощью HTTP-01 проверки.
4. Примените манифест для объекта ClusterIssuer:
```console
$ kubectl apply -f http01-clusterissuer.yaml
```
После выполнения всех шагов, у вас будет настроен доступ к образу ANIC, чарт развернут в Kubernetes, а cert-manager будет управлять сертификатами.
## Развертывание ANIC и тестового приложения в Kubernetes
1. Настройте домен и поиск внешнего IP-адреса. Создайте Ingress-ресурс, сервис и деплоймент для тестового приложения.
Замените доменное имя `otus-kube.mtdlb.ru` на ваш действующий домен.
Внешний IP-адрес кластера можно найти в Яндекс.Облаке в разделе `Managed Service for Kubernetes` → `Кластеры` → `otus` → `Сеть`.
Этот IP-адрес будет использоваться для привязки домена.
### app-angie.yaml
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: minimal-ingress
annotations:
cert-manager.io/cluster-issuer: "http01-clusterissuer"
acme.cert-manager.io/http01-edit-in-place: "true"
spec:
ingressClassName: angie
tls:
- hosts:
- otus-kube.mtdlb.ru
secretName: domain-name-secret
rules:
- host: otus-kube.mtdlb.ru
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: app
port:
number: 80
---
apiVersion: v1
kind: Service
metadata:
name: app
spec:
selector:
app: app
ports:
- protocol: TCP
port: 80
targetPort: 80
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: app-deployment
labels:
app: app
spec:
replicas: 1
selector:
matchLabels:
app: app
template:
metadata:
labels:
app: app
spec:
containers:
- name: app
image: angie:latest
ports:
- containerPort: 80
```
2. Запустите приложение:
```console
$ kubectl apply -f app-angie.yaml
```
3. Проверьте статус SSL-сертификата и его секрет в Kubernetes:
```console
$ kubectl describe certificate domain-name-secret
$ kubectl describe secret domain-name-secret
```
## Проверка работы
Откройте в браузере домен, который вы указали в конфигурации (например, [https://otus-kube.mtdlb.ru](https://otus-kube.mtdlb.ru)).
Если возникают проблемы, можно проверить логи подов:
```console
$ kubectl logs -l app=app
```
Также можно посмотреть конфигурацию ANIC (подставьте в `anic-64ff957589-jlg7s` имя пода с ANIC в вашем кластере):
```console
$ kubectl exec anic-64ff957589-jlg7s -- angie -T
```
## Удаление развернутого приложения
Если нужно удалить все созданные ресурсы, выполните:
```console
$ kubectl delete -f app-angie.yaml
```
## Проксирование TCP-трафика через ANIC в Kubernetes
Ниже приведен пример настройки проксирования TCP-трафика для доступа к MySQL.
Предварительно необходимо включить `globalConfiguration` в `values.yaml` чарта,
за счет него можно определить `listener`.
1. Установите чарт с выключенным параметром `globalConfiguration`:
```yaml
globalConfiguration:
## Creates the GlobalConfiguration custom resource. Requires controller.enableCustomResources.
create: false
```
2. Выполните команду:
```console
$ helm upgrade anic .
```
3. Теперь установите чарт с включенным параметром `globalConfiguration` и добавьте TCP-прослушиватель:
```yaml
globalConfiguration:
## Creates the GlobalConfiguration custom resource. Requires controller.enableCustomResources.
create: true
## The spec of the GlobalConfiguration for defining the global configuration parameters of the Ingress Controller.
spec:
listeners:
# - name: dns-udp
# port: 5353
# protocol: UDP
- name: mysql-tcp
port: 13306
protocol: TCP
```
4. Обновите чарт:
```console
$ helm upgrade anic .
```
Теперь ANIC будет слушать TCP-порт 13306 для подключения к MySQL.
5. Создайте секрет с паролем root:
### mysql-seceret.yaml
```yaml
apiVersion: v1
kind: Secret
metadata:
name: mysql-secret
type: kubernetes.io/basic-auth
stringData:
password: kljJ218q23cujvdshi
```
6. Создайте постоянное хранилище (volume) для MySQL:
### mysql-storage.yaml
```yaml
apiVersion: v1
kind: PersistentVolume
metadata:
name: mysql-pv-volume
labels:
type: local
spec:
storageClassName: manual
capacity:
storage: 10Gi
accessModes:
- ReadWriteOnce
hostPath:
path: "/mnt/data"
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: mysql-pv-claim
spec:
storageClassName: manual
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 10Gi
```
7. Разверните сам MySQL:
### mysql-deployment.yaml
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: mysql
spec:
selector:
matchLabels:
app: mysql
strategy:
type: Recreate
template:
metadata:
labels:
app: mysql
spec:
containers:
- image: mysql:8.0
name: mysql
env:
- name: MYSQL_ROOT_PASSWORD
valueFrom:
secretKeyRef:
name: mysql-secret
key: password
ports:
- containerPort: 3306
name: mysql
volumeMounts:
- name: mysql-persistent-storage
mountPath: /var/lib/mysql
volumes:
- name: mysql-persistent-storage
persistentVolumeClaim:
claimName: mysql-pv-claim
---
apiVersion: v1
kind: Service
metadata:
name: mysql
spec:
ports:
- port: 3306
selector:
app: mysql
```
8. Создайте сервис для MySQL:
### mysql-service.yaml
```yaml
apiVersion: v1
kind: Service
metadata:
name: mysql-ext
spec:
type: LoadBalancer
ports:
- port: 13306
name: mysql
targetPort: 13306
# Kubernetes-метки селектора, использованные в шаблоне подов при создании объекта Deployment.
selector:
app: mysql-tcp
```
9. Настройте ANIC для MySQL:
### anic-mysql.yaml
```yaml
apiVersion: k8s.angie.software/v1alpha1
kind: TransportServer
metadata:
name: mysql-tcp
spec:
listener:
name: mysql-tcp
protocol: TCP
upstreams:
- name: mysql
service: mysql
port: 3306
action:
pass: mysql
```
10. Примените настройки, чтобы развернуть сервис:
```console
$ kubectl apply -f mysql-secret.yaml
$ kubectl apply -f mysql-storage.yaml
$ kubectl apply -f mysql-deployment.yaml
$ kubectl apply -f mysql-service.yaml
$ kubectl apply -f anic-mysql.yaml
```
Теперь трафик на порт 13306 будет перенаправляться в MySQL.
11. Проверьте статус:
```console
$ kubectl get svc # Список сервисов
$ kubectl describe gc # Описание GlobalConfiguration
$ kubectl describe ts mysql-tcp # Описание TCP-listener
$ kubectl describe service anic # Информация об ANIC
```
# https://angie.software/anic/docs/installation/migration.md
# Миграция с Ingress-NGINX Controller на ANIC
Для миграции ANIC должен быть [установлен](https://angie.software//anic/docs/installation/installation-with-helm.md#installation-with-helm) на том же хосте, где уже работает Ingress-NGINX Controller.
## Перенос конфигурации
1. Настройте [ConfigMap](https://angie.software//anic/docs/configuration/config.md#anic-config) для ANIC, добавив общие параметры для всех Ingress.
Эти параметры будут использоваться по умолчанию для всех Ingress, если конкретный манифест их не переопределяет.
2. В манифестах для сервисов измените аннотации Ingress-NGINX Controller на соответствующие аннотации ANIC, где это необходимо.
Для аннотаций, которые не поддерживаются в ANIC, используйте другие варианты настройки конфигурации (см. примеры ниже).
3. По очереди перенесите манифесты для сервисов, проверяя, что каждый манифест работает корректно.
#### NOTE
Не рекомендуется изменять поле `spec` в ресурсе Ingress. Реализации Ingress-NGINX Controller и ANIC отличаются, что может привести к проблемам совместимости.
## Соответствия для аннотаций
В таблице ниже приведены аннотации Ingress-NGINX Controller с эквивалентными аннотациями ANIC.
| Ingress-NGINX Controller | ANIC |
|-----------------------------------------------------|----------------------------------------|
| `nginx.ingress.kubernetes.io/configuration-snippet` | `angie.software/location-snippets` |
| `nginx.ingress.kubernetes.io/load-balance` | `angie.software/lb-method` |
| `nginx.ingress.kubernetes.io/proxy-buffering` | `angie.software/proxy-buffering` |
| `nginx.ingress.kubernetes.io/proxy-buffers-number` | `angie.software/proxy-buffers` |
| `nginx.ingress.kubernetes.io/proxy-buffer-size` | `angie.software/proxy-buffer-size` |
| `nginx.ingress.kubernetes.io/proxy-connect-timeout` | `angie.software/proxy-connect-timeout` |
| `nginx.ingress.kubernetes.io/proxy-read-timeout` | `angie.software/proxy-read-timeout` |
| `nginx.ingress.kubernetes.io/proxy-send-timeout` | `angie.software/proxy-send-timeout` |
| `nginx.ingress.kubernetes.io/rewrite-target` | `angie.software/rewrites` |
| `nginx.ingress.kubernetes.io/server-snippet` | `angie.software/server-snippets` |
| `nginx.ingress.kubernetes.io/ssl-redirect` | `ingress.kubernetes.io/ssl-redirect` |
Полный список аннотаций ANIC см. в разделе [Расширенная конфигурация с помощью аннотаций](https://angie.software//anic/docs/configuration/annotations.md#annotations).
## Глобальная конфигурация с помощью ConfigMap
В таблице ниже приведено ключи ConfigMap в Ingress-NGINX Controller и их эквиваленты в ANIC.
| Ingress-NGINX Controller | ANIC |
|----------------------------------|---------------------------------|
| `disable-access-log` | `access-log-off` |
| `hsts` | `hsts` |
| `hsts-include-subdomains` | `hsts-include-subdomains` |
| `hsts-max-age` | `hsts-max-age` |
| `http-snippet` | `http-snippets` |
| `keep-alive` | `keepalive-timeout` |
| `keep-alive-requests` | `keepalive-requests` |
| `load-balance` | `lb-method` |
| `location-snippet` | `location-snippets` |
| `log-format-escape-json` | `log-format-escaping: "json"` |
| `log-format-stream` | `stream-log-format` |
| `log-format-upstream` | `log-format` |
| `main-snippet` | `main-snippets` |
| `max-worker-connections` | `worker-connections` |
| `max-worker-open-files` | `worker-rlimit-nofile` |
| `proxy-body-size` | `client-max-body-size` |
| `proxy-buffering` | `proxy-buffering` |
| `proxy-buffers-number` | `proxy-buffers: number size` |
| `proxy-buffer-size` | `proxy-buffers: number size` |
| `proxy-connect-timeout` | `proxy-connect-timeout` |
| `proxy-read-timeout` | `proxy-read-timeout` |
| `proxy-send-timeout` | `proxy-send-timeout` |
| `server-name-hash-bucket-size` | `server-names-hash-bucket-size` |
| `proxy-headers-hash-max-size` | `server-names-hash-max-size` |
| `server-snippet` | `server-snippets` |
| `server-tokens` | `server-tokens` |
| `upstream-keepalive-connections` | `keepalive` |
| `use-http2` | `http2` |
| `use-proxy-protocol` | `proxy-protocol` |
| `variables-hash-bucket-size` | `variables-hash-bucket-size` |
| `worker-cpu-affinity` | `worker-cpu-affinity` |
| `worker-processes` | `worker-processes` |
| `worker-shutdown-timeout` | `worker-shutdown-timeout` |
## Примеры
### Настройка терминации SSL и маршрутизации на основе HTTP-путей
Ingress-NGINX Controller:
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: nginx-test
spec:
tls:
- hosts:
- foo.bar.com
secretName: tls-secret
rules:
- host: foo.bar.com
http:
paths:
- path: /login
backend:
serviceName: login-svc
servicePort: 80
- path: /billing
serviceName: billing-svc
servicePort: 80
```
ANIC:
```yaml
apiVersion: networking.k8s.io/v1
kind: VirtualServer
metadata:
name: anic-test
spec:
host: foo.bar.com
tls:
secret: tls-secret
upstreams:
- name: login
service: login-svc
port: 80
- name: billing
service: billing-svc
port: 80
routes:
- path: /login
action:
pass: login
- path: /billing
action:
pass: billing
```
### Настройка балансировки нагрузки TCP/UDP и TLS Passthrough
ANIC предоставляет доступ к TCP- и UDP-сервисам с помощью ресурсов TransportServer и GlobalConfiguration.
Ingress-NGINX Controller использует для этой цели ConfigMap.
### Канареечные развертывания
Канареечные и сине-зеленые развертывания (сanary deployment и blue-green deployment) позволяют
внедрять изменения в код в продакшн-среде, не прерывая работу пользователей.
ANIC выполняет развертывания на уровне передачи данных: чтобы перейти с Ingress-NGINX Controller на ANIC,
необходимо сопоставить аннотации Ingress-NGINX Controller с ресурсами VirtualServer и VirtualServerRoute в ANIC.
Ingress-NGINX Controller обрабатывает канареечные аннотации в следующем порядке:
1. `nginx.ingress.kubernetes.io/canary-by-header`
2. `nginx.ingress.kubernetes.io/canary-by-cookie`
3. `nginx.ingress.kubernetes.io/canary-by-weight`
#### NOTE
Чтобы канареечные аннотации интерпретировались в ANIC аналогично, они должны располагаться в манифесте VirtualServer или VirtualServerRoute в том же порядке.
### nginx.ingress.kubernetes.io/canary-by-header
Ingress-NGINX Controller:
```yaml
nginx.ingress.kubernetes.io/canary: "true"
nginx.ingress.kubernetes.io/canary-by-header: "httpHeader"
```
ANIC:
```yaml
matches:
- conditions:
- header: httpHeader
value: never
action:
pass: echo
- header: httpHeader
value: always
action:
pass: echo-canary
action:
pass: echo
```
Ingress-NGINX Controller:
```yaml
nginx.ingress.kubernetes.io/canary: "true"
nginx.ingress.kubernetes.io/canary-by-header: "httpHeader"
nginx.ingress.kubernetes.io/canary-by-header-value: "my-value"
```
ANIC:
```yaml
matches:
- conditions:
- header: httpHeader
value: my-value
action:
pass: echo-canary
action:
pass: echo
```
### nginx.ingress.kubernetes.io/canary-by-cookie
Ingress-NGINX Controller:
```yaml
nginx.ingress.kubernetes.io/canary: "true"
nginx.ingress.kubernetes.io/canary-by-cookie: "cookieName"
```
ANIC:
```yaml
matches:
- conditions:
- cookie: cookieName
value: never
action:
pass: echo
- cookie: cookieName
value: always
action:
pass: echo-canary
action:
pass: echo
```
### Управление трафиком
Аннотации Ingress-NGINX Controller, для которых пока нет соответствующих полей в ресурсах ANIC, необходимо обрабатывать с помощью фрагментов (сниппетов).
#### NOTE
Для работы в чарте необходимо установить `controller.enableSnippets` в `true`.
В примерах ниже аннотации Ingress-NGINX Controller сопоставлены с ресурсами VirtualServer
и VirtualServerRoute в ANIC.
### custom-http-errors
Ingress-NGINX Controller:
```yaml
nginx.ingress.kubernetes.io/custom-http-errors: "code"
nginx.ingress.kubernetes.io/default-backend: "default-svc"
```
ANIC:
```yaml
errorPages:
- codes: [code]
redirect:
code: 301
url: default-svc
```
### limit-connections
Ingress-NGINX Controller:
```yaml
nginx.ingress.kubernetes.io/limit-connections: "number"
```
ANIC:
```yaml
http-snippets: |
limit_conn_zone $binary_remote_addr zone=zone_name:size;
routes:
- path: /path
location-snippets: |
limit_conn zone_name number;
```
### limit-rate
Ingress-NGINX Controller:
```yaml
nginx.ingress.kubernetes.io/limit-rate: "number"
nginx.ingress.kubernetes.io/limit-rate-after: "number"
```
ANIC:
```yaml
location-snippets: |
limit_rate number;
limit_rate_after number;
```
### limit-rpm
Ingress-NGINX Controller:
```yaml
nginx.ingress.kubernetes.io/limit-rpm: "number"
nginx.ingress.kubernetes.io/limit-burst-multiplier: "multiplier"
```
ANIC:
```yaml
rateLimit:
rate: numberr/m
burst: number * multiplier
key: ${binary_remote_addr}
zoneSize: size
```
### limit-rps
Ingress-NGINX Controller:
```yaml
nginx.ingress.kubernetes.io/limit-rps: "number"
nginx.ingress.kubernetes.io/limit-burst-multiplier: "multiplier"
```
ANIC:
```yaml
rateLimit:
rate: numberr/s
burst: number * multiplier
key: ${binary_remote_addr}
zoneSize: size
```
### limit-whitelist
Ingress-NGINX Controller:
```yaml
nginx.ingress.kubernetes.io/limit-whitelist: "CIDR"
```
ANIC:
```yaml
http-snippets: |
server-snippets: |
```
### rewrite-target
Ingress-NGINX Controller:
```yaml
nginx.ingress.kubernetes.io/rewrite-target: "URI"
```
ANIC:
```yaml
rewritePath: "URI"
```
### Манипуляция заголовками
Ingress-NGINX Controller:
```yaml
nginx.ingress.kubernetes.io/enable-cors: "true"
nginx.ingress.kubernetes.io/cors-allow-credentials: "true"
nginx.ingress.kubernetes.io/cors-allow-headers: :samp:`X-Forwarded-For`
nginx.ingress.kubernetes.io/cors-allow-methods: "PUT, GET, POST, OPTIONS"
nginx.ingress.kubernetes.io/cors-allow-origin: "*"
nginx.ingress.kubernetes.io/cors-max-age: "seconds"
```
ANIC:
Установка для Ingress возможна с помощью аннотации `angie.software/location-snippets`.
Для работы в чарте необходимо установить `controller.enableSnippets` в `true`.
```yaml
Ingress:
annotations:
angie.software/location-snippets |
add_header 'Access-Control-Allow-Origin' '*' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range' always;
add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always;
```
```yaml
VirtualServer
responseHeaders:
add:
- name: Access-Control-Allow-Credentials
value: "true"
- name: Access-Control-Allow-Headers
value: :samp:`X-Forwarded-For`
- name: Access-Control-Allow-Methods
value: "PUT, GET, POST, OPTIONS"
- name: Access-Control-Allow-Origin
value: "*"
- name: Access-Control-Max-Age
value: "seconds"
```
### Проксирование и балансировка нагрузки
В таблице ниже приведены аннотации Ingress-NGINX Controller и параметры в поле `upstream` для ресурсов VirtualServer и VirtualServerRoute.
| Ingress-NGINX Controller | ANIC |
|-----------------------------------------------------------|-------------------------|
| `nginx.ingress.kubernetes.io/load-balance` | `lb-method` |
| `nginx.ingress.kubernetes.io/proxy-buffering` | `buffering` |
| `nnginx.ingress.kubernetes.io/proxy-buffers-number` | `buffers` |
| `nginx.ingress.kubernetes.io/proxy-next-upstream` | `next-upstream` |
| `nginx.ingress.kubernetes.io/proxy-next-upstream-timeout` | `next-upstream-timeout` |
| `nginx.ingress.kubernetes.io/proxy-read-timeout` | `read-timeout` |
| `nginx.ingress.kubernetes.io/proxy-send-timeout` | `send-timeout` |
| `nginx.ingress.kubernetes.io/service-upstream` | `use-cluster-ip` |
### Аутентификация mTLS
ANIC может обрабатывать аутентификацию mTLS на уровне входного трафика, требуя предоставления действительных сертификатов для внешних соединений. Настройка реализуется с помощью ресурсов Policy, соответствующих аннотациям Ingress-NGINX Controller.
Ingress-NGINX Controller:
```yaml
nginx.ingress.kubernetes.io/auth-tls-secret: secretName
nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
```
ANIC:
```yaml
ingressMTLS:
clientCertSecret: secretName
verifyClient: "on"
verifyDepth: 1
```
Ingress-NGINX Controller:
```yaml
nginx.ingress.kubernetes.io/proxy-ssl-secret: "secretName"
nginx.ingress.kubernetes.io/proxy-ssl-verify: "on|off"
nginx.ingress.kubernetes.io/proxy-ssl-verify-depth: "1"
nginx.ingress.kubernetes.io/proxy-ssl-protocols: "TLSv1.2"
nginx.ingress.kubernetes.io/proxy-ssl-ciphers: "DEFAULT"
nginx.ingress.kubernetes.io/proxy-ssl-name: "server-name"
nginx.ingress.kubernetes.io/proxy-ssl-server-name: "on|off"
```
ANIC:
```yaml
egressMTLS:
tlsSecret: secretName
verifyServer: true|false
verifyDepth: 1
protocols: TLSv1.2
ciphers: DEFAULT
sslName: server-name
serverName: true|false
```
### Сохранение сессий
Для сохранения сессий в ANIC используются ресурсы Policy. В Ingress-NGINX Controller используются соответствующие аннотации.
Ingress-NGINX Controller:
```yaml
nginx.ingress.kubernetes.io/affinity: "cookie"
nginx.ingress.kubernetes.io/session-cookie-name: "cookieName"
nginx.ingress.kubernetes.io/session-cookie-expires: "x"
nginx.ingress.kubernetes.io/session-cookie-path: "/route"
nginx.ingress.kubernetes.io/session-cookie-secure: "true"
```
ANIC:
```yaml
sessionCookie:
enable: true
name: cookieName
expires: xh
path: /route
secure: true
```
### Аутентификация через внешний сервис
Ingress-NGINX Controller:
```yaml
nginx.ingress.kubernetes.io/auth-url
```
ANIC:
Используется собственная реализация (применима только для VirtualServer): [настройка OIDC](https://angie.software//anic/docs/custom-resources/configuring-oidc.md#configuring-oidc).
### Привязка sticky-сессий через cookie
Ingress-NGINX Controller:
```yaml
nginx.ingress.kubernetes.io/affinity: "cookie"
nginx.ingress.kubernetes.io/session-cookie-name: "cookie_name"
nginx.ingress.kubernetes.io/session-cookie-expires: "seconds"
nginx.ingress.kubernetes.io/session-cookie-path: "/route"
```
ANIC:
```yaml
angie.software/sticky-cookie-services: "serviceName=example-svc cookie_name expires=time path=/route"
```
# https://angie.software/anic/docs/configuration.md
# Настройка
Настройка ANIC включает настройку параметров через ConfigMap и аннотации, управление маршрутизацией Ingress-ресурсов и настройку авторизации и SSL для безопасного трафика.
> [Аргументы командной строки](https://angie.software//anic/docs/configuration/command-line-arguments.md#command-line-arguments)
> [Настройка ANIC](https://angie.software//anic/docs/configuration/config.md#anic-config)
> [ConfigMap](https://angie.software//anic/docs/configuration/configmap-resource.md#configmap-resource)
> [GlobalConfiguration](https://angie.software//anic/docs/configuration/globalconfiguration-resource.md#globalconfiguration-resource)
> [Policy](https://angie.software//anic/docs/configuration/policy-resource.md#policy-resource)
> [TransportServer](https://angie.software//anic/docs/configuration/transportserver-resource.md#transportserver-resource)
> [VirtualServer, VirtualServerRoute](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserver-and-virtualserverroute-resources)
> [Расширенная конфигурация с помощью аннотаций](https://angie.software//anic/docs/configuration/annotations.md#annotations)
# https://angie.software/anic/docs/configuration/command-line-arguments.md
# Аргументы командной строки
ANIC поддерживает ряд аргументов командной строки. Способ
указания этих аргументов зависит от того, как вы устанавливаете ANIC:
- Если вы используете *манифесты Kubernetes* (Deployment или DaemonSet) для
установки ANIC, измените эти манифесты соответствующим образом, чтобы задать
аргументы командной строки. См. документацию по установке с манифестами.
- Если вы используете *Helm* для установки ANIC, измените
параметры диаграммы Helm, соответствующие аргументам командной строки. См.
документацию по [установке с помощью Helm](https://angie.software//anic/docs/installation/installation-with-helm.md#installation-with-helm).
Ниже в алфавитном порядке перечислены доступные аргументы командной строки:
## -angie-configmaps `<строка>`
Ресурс ConfigMap для настройки конфигурации Angie. Если ConfigMap задан,
но ANIC не может получить его из API Kubernetes, то
ANIC не запустится.
Формат: `<пространство имен>/<имя>`
## -angie-dashboard
Включает Angie Dashboard (status endpoint для получения информации о состоянии Angie).
## -angie-dashboard-port ``
Задает порт, на котором доступен Angie Dashboard (по умолчанию `8082`).
Формат: `[1024 - 65535]`
## -angie-dashboard-allow-cidrs `<строка>`
Добавляет блоки IP/CIDR в список разрешений для Angie Dashboard.
Несколько IP или CIDR разделяются запятыми.
## -angie-debug
Включает отладку для Angie. Использует бинарник angie-debug. Требуется
'error-log-level: debug' в ConfigMap.
## -angie-reload-timeout `<значение>`
Время ожидания в миллисекундах, в течение которого ANIC
будет ожидать успешной перезагрузки Angie после изменения конфигурации
или при начальном запуске.
Значение по умолчанию - 60000.
## -angie-status
Включает Angie stub_status.
По умолчанию `true`.
## -angie-status-allow-cidrs `<строка>`
Добавляет блоки IP/CIDR в список разрешений для Angie stub_status.
Несколько IP или CIDR разделяются запятыми. (По умолчанию
`127.0.0.1,::1`)
## -angie-status-port ``
Задает порт, на котором доступен Angie stub_status.
Формат: `[1024 - 65535]` (по умолчанию `8080`)
## -angie-status-prometheus ``
Включает или отключает выдачу [статистики Angie в формате Prometheus](https://angie.software/configuration/modules/http_prometheus/).
Формат: `false` или `true` (по умолчанию `true`)
## -angie-status-prometheus-allow-cidrs
Добавляет блоки IP/CIDR в список разрешений для
[статистики Angie в формате Prometheus](https://angie.software/configuration/modules/http_prometheus/).
Несколько IP или CIDR разделяются запятыми. (По умолчанию
`127.0.0.1,::1`)
## -angie-status-prometheus-path `<строка>`
Позволяет менять путь для публикации [статистики Angie в формате Prometheus](https://angie.software/configuration/modules/http_prometheus/).
По умолчанию используется `/p8s`.
## -angie-status-prometheus-port ``
Задает порт, на котором доступна [статистика Angie в формате Prometheus](https://angie.software/configuration/modules/http_prometheus/).
Формат: `[1024 - 65535]` (по умолчанию `8083`)
## -default-server-tls-secret `<строка>`
Секрет с сертификатом TLS и ключом для TLS-терминации на сервере по
умолчанию.
- Если значение не задано, используются сертификат и ключ в файле
`/etc/angie/secrets/default`.
- Если `/etc/angie/secrets/default` не существует, ANIC
настроит в Angie отклонение TLS-подключений к серверу по умолчанию.
- Если секрет установлен, но ANIC не может получить его
из API Kubernetes, или же не установлен, и ANIC не
удается прочитать файл `/etc/angie/secrets/default`, то ANIC
не запустится.
Формат: `<пространство имен>/<имя>`
## -disable-ipv6
Явно отключает прослушиватели IPV6 для узлов, которые не поддерживают
стек IPV6.
По умолчанию `false`.
## -enable-cert-manager
Включает автоматическое управление сертификатами x509 для ресурсов
VirtualServer с помощью cert-manager (cert-manager.io).
Требует
[-enable-custom-resources](#enable-custom-resources).
## -enable-custom-resources
Включает пользовательские ресурсы.
По умолчанию `true`.
## -enable-external-dns
Включает интеграцию с ExternalDNS для настройки общедоступных записей
DNS у ресурсов VirtualServer с использованием
[ExternalDNS](https://github.com/kubernetes-sigs/external-dns).
Требует наличия
[-enable-custom-resources](#enable-custom-resources).
## -enable-jwt
Включает функцию аутентификации JWT в ресурсах Policy.
По умолчанию `false`.
## -enable-leader-election
Позволяет выбирать лидера, чтобы избежать ситуации, когда несколько
реплик контроллера сообщают о статусе ресурсов Ingress, VirtualServer и
VirtualServerRoute; сообщать о статусе будет только одна реплика. По
умолчанию `true`.
См. флаг [-report-ingress-status](#report-ingress-status).
## -enable-oidc
Включает функцию аутентификации по OpenID Connect в ресурсах Policy.
По умолчанию `false`.
## -enable-prometheus-metrics
Позволяет публиковать метрики Angie в формате Prometheus.
## -enable-service-insight
Публикует конечную точку Service Insight для ANIC.
## -enable-snippets
Включает пользовательские фрагменты конфигурации Angie в ресурсах
Ingress, VirtualServer, VirtualServerRoute и TransportServer.
По умолчанию `false`.
## -enable-tls-passthrough
Включает сквозную передачу данных по протоколу TLS на порту 443.
Требует наличия
[-enable-custom-resources](#enable-custom-resources).
## -external-service `<строка>`
Указывает имя сервиса с типом LoadBalancer, через который поды ANIC
делаются доступными извне. Внешний адрес сервиса используется
для отчетов о состоянии ресурсов Ingress, VirtualServer и
VirtualServerRoute.
Только для ресурсов Ingress: требует наличия
[-report-ingress-status](#report-ingress-status).
## -global-configuration `<строка>`
Ресурс GlobalConfiguration для глобальной настройки ANIC.
Формат:`<пространство имен>/<имя>`
Требует наличия
[-enable-custom-resources](#enable-custom-resources).
## -health-status
Добавляет местоположение "/angie-health" к серверу по умолчанию.
Местоположение отвечает кодом статуса 200 на любой запрос.
Это полезно для внешней проверки работоспособности ANIC.
## -health-status-uri `<строка>`
Задает URI местоположения проверки работоспособности на сервере по
умолчанию. Требует наличия
[-health-status](#health-status).
По умолчанию `/angie-health`.
## -ingress-class `<строка>`
Класс ANIC.
Должен быть развернут соответствующий ресурс IngressClass с именем,
равным классу. В противном случае ANIC не запустится.
ANIC обрабатывает только те ресурсы, которые принадлежат
его классу, т. е. имеют ресурс поля `ingressClassName`, равный классу.
ANIC обрабатывает все ресурсы, у которых нет поля
`ingressClassName`.
По умолчанию `angie`.
## -ingresslink `<строка>`
Указывает имя ресурса IngressLink, через который предоставляется доступ
к подам ANIC через систему BIG-IP. IP-адрес системы BIG-IP
используется для отчетов о состоянии ресурсов Ingress, VirtualServer и
VirtualServerRoute.
Только для ресурсов Ingress: требует наличия
[-report-ingress-status](#report-ingress-status).
## -ingress-template-path `<строка>`
Путь к шаблону конфигурации Ingress Angie для ресурса Ingress. По
умолчанию для Angie используется `angie.ingress.tmpl`.
## -leader-election-lock-name `<строка>`
Указывает в том же пространстве имен, где находится контроллер, имя
ConfigMap, используемое для блокировки при выборе лидера.
Требует наличия
[-enable-leader-election](#enable-leader-election).
## -main-template-path `<строка>`
Путь к основному шаблону конфигурации Angie.
- По умолчанию для Angie используется `angie.ingress.tmpl`.
## -prometheus-metrics-listen-port ``
Задает порт, на котором публикуются метрики Prometheus.
Формат: `[1024 - 65535]` (по умолчанию `9113`)
## -prometheus-tls-secret `<строка>`
Секрет с сертификатом TLS и ключом для TLS-терминации конечной точки
метрик Prometheus.
- Если аргумент не задан, конечная точка Prometheus не будет
использовать TLS-соединение.
- Если аргумент задан, но ANIC не может получить секрет
из API Kubernetes, то ANIC не запустится.
## -proxy `<строка>`
Задает использование прокси-сервера для подключения к API Kubernetes,
запускаемого командой "kubectl proxy". **Только в целях тестирования**.
ANIC не запускает Angie и не записывает на диск никакие
сгенерированные файлы конфигурации Angie.
## -ready-status
Включает конечную точку готовности `/angie-ready`. Конечная точка
возвращает код успеха, когда Angie загрузил всю конфигурацию после
запуска.
По умолчанию `true`.
## -ready-status-port
HTTP-порт для конечной точки готовности.
Формат: `[1024 - 65535]` (по умолчанию `8081`)
## -report-ingress-status
Обновляет поле адреса в статусе ресурсов Ingress.
Требуется флаг [-external-service](#external-service-string) или
[-ingresslink](#ingresslink-string), либо ключ `external-status-address`
в ConfigMap.
## -service-insight-listen-port ``
Задает порт, на котором публикуется Service Insight.
Формат: `[1024 - 65535]` (по умолчанию `9114`)
## -service-insight-tls-secret `<строка>`
Секрет с сертификатом TLS и ключом для TLS-терминации конечной точки
Service Insight.
- Если аргумент не задан, конечная точка Service Insight не будет
использовать TLS-соединение.
- Если аргумент задан, но ANIC не может получить секрет
из API Kubernetes, то ANIC не запустится.
Формат: `<пространство имен>/<имя>`
## -tls-passthrough-port ``
Задает порт для сквозной передачи данных по протоколу TLS. Формат:
`[1024 - 65535]` (по умолчанию `443`)
Требует включить
[-enable-custom-resources](#enable-custom-resources).
## -transportserver-template-path `<строка>`
Путь к шаблону конфигурации TransportServer Angie для ресурса
TransportServer.
- По умолчанию для Angie используется`angie.transportserver.tmpl`.
## -v `<значение>`
Уровень детализации записи логов. Значение по умолчанию — `1`, при этом значении записывается минимальное количество логов. Значение `3` полезно для устранения неполадок.
## -version
Выводит версию, хэш git-коммита и дату сборки, затем завершает работу.
## -virtualserver-template-path `<строка>`
Путь к шаблону конфигурации VirtualServer Angie для ресурса
VirtualServer.
- По умолчанию для Angie используется `angie.ingress.tmpl`.
## -vmodule `<значение>`
Разделенный запятыми список параметров pattern=N для ведения журнала с
фильтрацией файлов.
## -watch-namespace `<строка>`
Разделенный запятыми список пространств имен, за ресурсами которых
должен следить ANIC. По умолчанию ANIC
отслеживает все пространства имен. Нельзя использовать вместе с
"watch-namespace-label".
## -watch-namespace-label `<строка>`
Настраивает в ANIC просмотр только пространств имен с
меткой foo=bar. По умолчанию ANIC отслеживает все
пространства имен. Нельзя использовать вместе с "watch-namespace".
## -watch-secret-namespace `<строка>`
Разделенный запятыми список пространств имен, за которыми ANIC
должен следить на предмет наличия секретов. Если этот
параметр не настроен, ANIC отслеживает одни и те же
пространства имен для всех ресурсов. См. также "watch-namespace" и
"watch-namespace-label".
## -wildcard-tls-secret `<строка>`
Секрет с сертификатом TLS и ключом для TLS-терминации каждого узла
Ingress или VirtualServer, для которого включена TLS-терминация, но
секрет не указан.
- Если аргумент не задан, для таких узлов Ingress и VirtualServer Angie
прервет любую попытку установить TLS-соединение.
- Если аргумент задан, но ANIC не может получить секрет
из API Kubernetes, то ANIC не запустится.
Формат: `<пространство имен>/<имя>`
# https://angie.software/anic/docs/configuration/config.md
# Настройка ANIC
Здесь приведены параметры настройки ANIC. ANIC настраивается путем изменения параметров `ConfigMap` и `Annotation`.
```yaml
$ kubectl apply -f - <
клиентский запрос, если для запроса не был определен ресурс `Ingress`
или `VirtualServer`. Можно установить фиксированный ответ или
перенаправление запроса. | Страница с ошибкой HTTP 404 |
| `server-tokens` | Включает или отключает [server_tokens](https://angie.software//angie/docs/configuration/modules/http/index.md#server-tokens) | `True` |
| `worker-processes` | Задает значение [worker_processes](https://angie.software//angie/docs/configuration/modules/core.md#worker-processes) | `auto` |
| `worker-rlimit-nofile` | Задает значение [worker_rlimit_nofile](https://angie.software//angie/docs/configuration/modules/core.md#worker-rlimit-nofile) | Нет |
| `worker-connections` | Задает значение [worker_connections](https://angie.software//angie/docs/configuration/modules/core.md#worker-connections) | `1024` |
| `worker-cpu-affinity` | Задает значение [worker_cpu_affinity](https://angie.software//angie/docs/configuration/modules/core.md#worker-cpu-affinity) | Нет |
| `worker-shutdown-timeout` | Задает значение [worker_shutdown_timeout](https://angie.software//angie/docs/configuration/modules/core.md#worker-shutdown-timeout) | Нет |
| `server-names-hash-bucket-size` | Задает значение [server_names_hash_bucket_size](https://angie.software//angie/docs/configuration/modules/http/index.md#server-names-hash-bucket-size) | `256` |
| `server-names-hash-max-size` | Задает значение [server_names_hash_max_size](https://angie.software//angie/docs/configuration/modules/http/index.md#server-names-hash-max-size) | `1024` |
| `map-hash-bucket-size` | Задает значение [map_hash_bucket_size](https://angie.software//angie/docs/configuration/modules/http/http_map.md#map-hash-bucket-size) | `256` |
| `map-hash-max-size` | Задает значение [map_hash_max_size](https://angie.software//angie/docs/configuration/modules/http/http_map.md#map-hash-max-size) | `2048` |
| `resolver-addresses` | Задает значение DNS [resolver](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver) | Нет |
| `resolver-ipv6` | Разрешает или запрещает поиск IPv6-адресов | `True` |
| `resolver-valid` | Позволяет переопределить срок кэширования DNS-записей | Нет |
| `resolver-timeout` | Задает значение [resolver_timeout](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver-timeout) | `30s` |
| `keepalive-timeout` | Задает значение [keepalive_timeout](https://angie.software//angie/docs/configuration/modules/http/index.md#keepalive-timeout) | `65s` |
| `keepalive-requests` | Задает значение [keepalive_requests](https://angie.software//angie/docs/configuration/modules/http/index.md#keepalive-requests) | `100` |
| `variables-hash-bucket-size` | Задает значение [variables_hash_bucket_size](https://angie.software//angie/docs/configuration/modules/http/index.md#variables-hash-bucket-size) | `256` |
| `variables-hash-max-size` | Задает значение [variables_hash_max_size](https://angie.software//angie/docs/configuration/modules/http/index.md#variables-hash-max-size) | `1024` |
## Параметры ведения журнала
| Параметр | Описание | Умолчание |
|---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
| `error-log-level` | Определяет глобальное значение уровня [error_log](https://angie.software//angie/docs/configuration/modules/core.md#error-log) и может принимать одно из следующих значений:
debug, info, notice, warn, error, crit, alert или emerg | `notice` |
| `access-log-off` | Отключает [access_log](https://angie.software//angie/docs/configuration/modules/http/http_log.md#access-log) | `False` |
| `default-server-access-log-off` | Отключает [access_log](https://angie.software//angie/docs/configuration/modules/http/http_log.md#access-log) для сервиса по
умолчанию | `False` |
| `log-format` | Задает [общий формат журнала](https://angie.software//angie/docs/configuration/modules/http/http_log.md#log-format). Для
удобства можно использовать несколько строк, разделенных `n`. В этом
случае каждый перевод строки будет заменен на пробел. Все символы `'`
должны быть экранированы | Нет |
| `log-format-escaping` | Позволяет задать [экранирование символов](https://angie.software//angie/docs/configuration/modules/http/http_log.md#log-format)
`json` или `default` в переменных; по умолчанию используется
`default`. Значение `none` отключает экранирование | `default` |
| `stream-log-format` | Задает [формат журнала stream](https://angie.software//angie/docs/configuration/modules/stream/stream_log.md#s-log-format) для
сквозного трафика TCP, UDP и TLS. Для удобства можно использовать
несколько строк, разделенных `n`. В этом случае каждый перевод строки
будет заменен на пробел. Все символы `'` должны быть экранированы | Нет |
| `stream-log-format-escaping` | Позволяет задать [экранирование символов](https://angie.software//angie/docs/configuration/modules/stream/stream_log.md#s-log-format) `json` или `default` в переменных; по
умолчанию используется `default`. Значение `none` отключает
экранирование | `default` |
## Управление URI и заголовками в запросах
| `proxy-hide-headers` | Значение одного [proxy_hide_header](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-hide-header) или нескольких |
|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| `proxy-pass-headers` | Значение одного
[proxy_pass_header](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass-header)
или нескольких |
## Авторизация и SSL/TLS
| Параметр | Описание | Умолчание |
|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|
| `redirect-to-https` | Задает правило 301 redirect в зависимости от заголовка
http_x_forwarded_proto | `False` |
| `ssl-redirect` | Задает правило 301 redirect для всего входящего HTTP-трафика, чтобы
перевести запросы в HTTPS | `True` |
| `ssl-protocols` | Задает значение [ssl_protocols](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-protocols) | `TLSv1 TLSv1.1 TLSv1.2` |
| `ssl-prefer-server-ciphers` | Включает или отключает [ssl_prefer_server_ciphers](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-prefer-server-ciphers) | `False` |
| `ssl-ciphers` | Задает значение [ssl_ciphers](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ciphers) | `HIGH:!aNULL:!MD5` |
| `ssl-dhparam-file` | Указывает [файл с параметрами для DHE-шифров](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-dhparam) | Нет |
## Протоколы
| Параметр | Описание | Умолчание |
|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
| `http2` | Включает поддержку [протокола](https://angie.software//angie/docs/configuration/modules/http/index.md#listen-protocols)
HTTP/2 | `False` |
| `proxy-protocol` | Указывает, что все соединения, принимаемые на данном слушающем
сокете, должны использовать [протокол](https://angie.software//angie/docs/configuration/modules/http/index.md#listen-protocols) PROXY | `False` |
## Апстримы
| Параметр | Описание | Умолчание |
|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
| `max-fails` | Задает значение `max_fails` для
[сервера](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) | `1` |
| `upstream-zone-size` | Задает имя и размер [зоны разделяемой памяти](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) | Нет |
| `fail-timeout` | Задает значение `fail_timeout` для
[сервера](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) | `10s` |
| `keepalive` | Задействует [кэш соединений](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive) для
группы серверов апстрима | Нет |
## Настраиваемые шаблоны
| `main-snippets` | Вставляет собственный фрагмент конфигурации в контекст [main](https://angie.software//angie/docs/configuration/configfile.md#configfile) |
|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `http-snippets` | Вставляет собственный фрагмент конфигурации в контекст [http](https://angie.software//angie/docs/configuration/configfile.md#configfile) |
| `location-snippets` | Вставляет собственный фрагмент конфигурации в контекст [location](https://angie.software//angie/docs/configuration/configfile.md#configfile) |
| `server-snippets` | Вставляет собственный фрагмент конфигурации в контекст [server](https://angie.software//angie/docs/configuration/configfile.md#configfile) |
| `stream-snippets` | Вставляет собственный фрагмент конфигурации в контекст [main](https://angie.software//angie/docs/configuration/configfile.md#configfile) |
| `main-template` | Определяет основной шаблон для основных настроек Angie. По умолчанию
шаблон считывается из файла в контейнере |
| `ingress-template` | Определяет шаблон настроек для ресурса Ingress. По умолчанию
шаблон считывается из файла в контейнере |
| `virtualserver-template` | Определяет шаблон настроек для ресурса [VirtualServer](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserver-and-virtualserverroute-resources). По умолчанию шаблон
считывается из файла в контейнере |
# https://angie.software/anic/docs/configuration/configmap-resource.md
# ConfigMap
ConfigMap позволяет настраивать поведение Angie.
Например, можно задать количество рабочих процессов или настроить формат журнала
доступа.
## Использование ConfigMap
1. Наши инструкции по установке с манифестами
развертывают пустой ConfigMap, в то время как манифесты установки по
умолчанию указывают ее в аргументах командной строки ANIC.
Однако, если вы настроили манифесты, чтобы использовать ConfigMap,
обязательно укажите ресурс ConfigMap для использования с помощью
[аргументов командной строки](https://angie.software//anic/docs/configuration/command-line-arguments.md#command-line-arguments) ANIC.
2. Создайте файл ConfigMap с именем `angie-config.yaml` и установите
значения, которые имеют смысл для вашей среды:
```yaml
kind: ConfigMap
apiVersion: v1
metadata:
name: angie-config
namespace: angie-ingress
data:
proxy-connect-timeout: 10s
proxy-read-timeout: 10s
client-max-body-size: 2m
```
См. в разделе [Краткое описание ключей
ConfigMap](#summary-of-configmap-keys) сведения о доступных ключах
ConfigMap (таких как `proxy-connect-timeout` в этом примере).
3. Создайте новый (или обновите существующий) ресурс ConfigMap:
```console
kubectl apply -f angie-config.yaml
```
Конфигурация Angie будет обновлена.
## ConfigMap и аннотации Ingress
Аннотации позволяют настраивать расширенные функции Angie и менять
поведение Angie.
ConfigMap применяется глобально, то есть влияет на каждый ресурс
Ingress. Напротив, аннотации всегда применяются только к своему ресурсу
Ingress. Аннотации позволяют переопределять некоторые ключи ConfigMap.
Например, в `angie.software/proxy-connect-timeout` аннотации
переопределяют ключ конфигурации `proxy-connect-timeout`.
## Переопределение ConfigMap для конкретного ресурса Ingress с помощью аннотации
Вы можете применять разные конфигурации ConfigMap к Ingress-ресурсам в зависимости от того, какое пространство имен указано в конфигурации. Аннотация `angie.software/configmap` позволяет задать конкретный ConfigMap для настройки ресурса Ingress. Заданный ConfigMap будет иметь приоритет над глобальным. В случае, если глобальный и заданный ConfigMap совпадают, применится заданный.
Чтобы применить конкретный ConfigMap к ресурсу Ingress:
1. Создайте ConfigMap с указанием нужного пространства имен.
Например:
> ```yaml
> kind: ConfigMap
> apiVersion: v1
> metadata:
> name: echoserver-new-config
> namespace: echoserver-new
> data:
> server-snippets: |
> location /echoserver-new-snippet {
> return 302 /echo-test-2;
> }
> ```
2. Укажите аннотацию `angie.software/configmap` в ресурсе Ingress, к которому нужно применить этот ConfigMap.
Например:
> ```yaml
> apiVersion: networking.k8s.io/v1
> kind: Ingress
> metadata:
> annotations:
> angie.software/configmap: "echoserver-new/echoserver-new-config"
> name: echoserver-new
> namespace: echoserver-new
> spec:
> ingressClassName: angie
> rules:
> - host: test-new.example.com
> http:
> paths:
> - backend:
> service:
> name: echoserver-new
> port:
> number: 8077
> pathType: ImplementationSpecific
> ```
В этом примере аннотация `angie.software/configmap` указывает на использование конфигурации из ConfigMap `echoserver-new-config`. Это означает, что директивы, описанные в `server-snippets` из этого ConfigMap, будут применяться к запросам, обрабатываемым этим Ingress.
См. также документацию по [расширенной конфигурации с помощью аннотаций](https://angie.software//anic/docs/configuration/annotations.md#annotations).
## ConfigMap и ресурсы VirtualServer, VirtualServerRoute
ConfigMap влияет на все ресурсы VirtualServer и VirtualServerRoute.
Однако поля этих ресурсов позволяют переопределять некоторые ключи
ConfigMap. Например, поле `connect-timeout` сервера `апстрима` имеет
приоритет над ключом ConfigMap `proxy-connect-timeout`.
См. документацию по [ресурсам VirtualServer и
VirtualServerRoute](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserver-and-virtualserverroute-resources).
## Краткое описание ключей ConfigMap
#### NOTE
Для всех параметров типа `boolean` допустимы пары значений `true`/ `false`, `t` / `f`, `on` / `off` и `1` / `0`. Регистр не имеет значения.
### ANIC (не связанные с конфигурацией Angie)
| Ключ ConfigMap | Описание | По умолчанию | Пример |
|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------|------------------------------------------------------------------------------------------------------------------------------------------------|
| `external-status-address` | Задает адрес, который будет отображаться в статусе ресурсов Ingress.
Требуется аргумент командной строки `-report-status`. Имеет приоритет
над аргументом `-external-service`. | Н/Д | [Отчет о состоянии Ingress](https://angie.software//anic/docs/logging-and-monitoring/reporting-resources-status.md#reporting-resources-status) |
### Общая настройка
| Ключ ConfigMap | Описание | По умолчанию | Пример |
|---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|----------|
| `proxy-connect-timeout` | Задает значение директив
[proxy_connect_timeout](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-connect-timeout)
и
[grpc_connect_timeout](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-connect-timeout). | `60s` | |
| `proxy-read-timeout` | Задает значение директив
[proxy_read_timeout](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-read-timeout)
и
[grpc_read_timeout](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-read-timeout). | `60s` | |
| `proxy-send-timeout` | Задает значение директив
[proxy_send_timeout](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-send-timeout)
и
[grpc_send_timeout](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-send-timeout). | `60s` | |
| `client-max-body-size` | Задает значение директивы
[client_max_body_size](https://angie.software//angie/docs/configuration/modules/http/index.md#client-max-body-size). | `1m` | |
| `proxy-buffering` | Включает или отключает [буферизацию
ответов](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-buffering) от
проксируемого сервера. | `True` | |
| `proxy-buffers` | Задает значение директивы
[proxy_buffers](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-buffers). | Зависит от платформы. | |
| `proxy-buffer-size` | Задает значение директив
[proxy_buffer_size](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-buffer-size)
и
[grpc_buffer_size](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-buffer-size). | Зависит от платформы. | |
| `proxy-max-temp-file-size` | Задает значение директивы
[proxy_max_temp_file_size](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-max-temp-file-size). | `1024m` | |
| `set-real-ip-from` | Задает значение директивы
[set_real_ip_from](https://angie.software//angie/docs/configuration/modules/http/http_realip.md#set-real-ip-from). | Н/Д | |
| `real-ip-header` | Задает значение директивы
[real_ip_header](https://angie.software//angie/docs/configuration/modules/http/http_realip.md#real-ip-header). | `X-Real-IP` | |
| `real-ip-recursive` | Включает или отключает директиву
[real_ip_recursive](https://angie.software//angie/docs/configuration/modules/http/http_realip.md#real-ip-recursive). | `False` | |
| `default-server-return` | Настраивает директиву [return](https://angie.software//angie/docs/configuration/modules/http/http_rewrite.md#return) на сервере по умолчанию, которая
обрабатывает клиентский запрос, если ни один из узлов ресурсов Ingress
или VirtualServer не совпадает. Значение по умолчанию настраивает в Angie
возврат страницы с ошибкой 404. Вы можете настроить фиксированный ответ
или перенаправление. Например, значение `default-server-return: 302
https://mysite.ru:samp:` перенаправит клиент на `https://mysite.ru`. | `404` | |
| `server-tokens` | Включает или отключает директиву
[server_tokens](https://angie.software//angie/docs/configuration/modules/http/index.md#server-tokens). | `True` | |
| `worker-processes` | Задает значение директивы
[worker_processes](https://angie.software//angie/docs/configuration/modules/core.md#worker-processes). | `auto` | |
| `worker-rlimit-nofile` | Задает значение директивы
[worker_rlimit_nofile](https://angie.software//angie/docs/configuration/modules/core.md#worker-rlimit-nofile). | Н/Д | |
| `worker-connections` | Задает значение директивы
[worker_connections](https://angie.software//angie/docs/configuration/modules/core.md#worker-connections). | `1024` | |
| `worker-cpu-affinity` | Задает значение директивы
[worker_cpu_affinity](https://angie.software//angie/docs/configuration/modules/core.md#worker-cpu-affinity). | Н/Д | |
| `worker-shutdown-timeout` | Задает значение директивы
[worker_shutdown_timeout](https://angie.software//angie/docs/configuration/modules/core.md#worker-shutdown-timeout). | Н/Д | |
| `server-names-hash-bucket-size` | Задает значение директивы
[server_names_hash_bucket_size](https://angie.software//angie/docs/configuration/modules/http/index.md#server-names-hash-bucket-size). | `256` | |
| `server-names-hash-max-size` | Задает значение директивы
[server_names_hash_max_size](https://angie.software//angie/docs/configuration/modules/http/index.md#server-names-hash-max-size). | `1024` | |
| `map-hash-bucket-size` | Задает значение директивы
[map_hash_bucket_size](https://angie.software//angie/docs/configuration/modules/http/http_map.md#map-hash-bucket-size). | `256` | |
| `map-hash-max-size` | Задает значение директивы
[map_hash_max_size](https://angie.software//angie/docs/configuration/modules/http/http_map.md#map-hash-max-size). | `2048` | |
| `resolver-addresses` | Задает значение адресов [resolver](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver). | Н/Д | |
| `resolver-ipv6` | Включает разрешение IPv6 в распознавателе. | `True` | |
| `resolver-timeout` | Задает значение [resolver_timeout](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver-timeout) для разрешения имен. | `30s` | |
| `keepalive-timeout` | Задает значение директивы
[keepalive_timeout](https://angie.software//angie/docs/configuration/modules/http/index.md#keepalive-timeout). | `65s` | |
| `keepalive-requests` | Задает значение директивы
[keepalive_requests](https://angie.software//angie/docs/configuration/modules/http/index.md#keepalive-requests). | `100` | |
| `variables-hash-bucket-size` | Задает значение директивы
[variables_hash_bucket_size](https://angie.software//angie/docs/configuration/modules/http/index.md#variables-hash-bucket-size). | `256` | |
| `variables-hash-max-size` | Задает значение директивы
[variables_hash_max_size](https://angie.software//angie/docs/configuration/modules/http/index.md#variables-hash-max-size). | `1024` | |
### Ведение журнала
| Ключ ConfigMap | Описание | По умолчанию | Пример |
|---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------|----------|
| `error-log-level` | Задает глобальный [уровень журнала
ошибок](https://angie.software//angie/docs/configuration/modules/core.md#error-log) для Angie. | `notice` | |
| `access-log-off` | Отключает [журнал доступа](https://angie.software//angie/docs/configuration/modules/core.md#error-log). | `False` | |
| `default-server-access-log-off` | Отключает [журнал доступа](https://angie.software//angie/docs/configuration/modules/core.md#error-log) для
сервера по умолчанию. Если журнал доступа отключен глобально
(`access-log-off: "True"`), то журнал доступа к серверу по умолчанию
всегда отключен. | `False` | |
| `log-format` | Задает настраиваемый [формат журнала](https://angie.software//angie/docs/configuration/modules/http/http_log.md#log-format) для HTTP- и
HTTPS-трафика. Для удобства можно определить формат журнала в нескольких
строках (строки разделяются символом `\n`). В этом случае ANIC заменит
каждый символ `\n` символом пробела. Все символы `'` должны быть
экранированы. | | |
| `log-format-escaping` | Задает экранирующие символы для переменных формата журнала.
Поддерживаемые значения: `json` (экранирование JSON), `default`
(экранирование по умолчанию), `none` (отключает экранирование). | `default` | |
| `stream-log-format` | Задает настраиваемый формат журнала для сквозного
трафика TCP, UDP и TLS. Для удобства можно определить формат журнала в
нескольких строках (строки разделяются символом `\n`). В этом случае
ANIC заменит каждый символ `\n` символом пробела. Все символы `'`
должны быть экранированы. | | |
| `stream-log-format-escaping` | Задает экранирующие символы для переменных формата журнала потока.
Поддерживаемые значения: `json` (экранирование JSON), `default`
(экранирование по умолчанию), `none` (отключает экранирование). | `default` | |
### Манипулирование URI и заголовками запроса
| Ключ ConfigMap | Описание | По умолчанию | Пример |
|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------|----------------------------------------------------------------|
| `proxy-hide-headers` | Задает значение одной директивы
[proxy_hide_header](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-hide-header)
или нескольких. | Н/Д | `"angie.software/proxy-hide-headers": "header-a,header-b"` |
| `proxy-pass-headers` | Задает значение одной директивы
[proxy_pass_header](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass-header)
или нескольких. | Н/Д | `"angie.software/proxy-pass-headers":
"header-a,header-b"` |
### Аутентификация, SSL, TLS
| Ключ ConfigMap | Описание | По умолчанию | Пример |
|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|----------|
| `redirect-to-https` | Задает правило перенаправления 301 на основе значения заголовка
`http_x_forwarded_proto` в серверном блоке, требуя, чтобы входящий
трафик шел по протоколу HTTPS. Полезно при терминации SSL в системе
балансировки нагрузки перед ANIC. | `False` | |
| `ssl-redirect` | Задает безусловное правило перенаправления 301 для всего входящего
HTTP-трафика, требуя, чтобы входящий трафик шел по протоколу HTTPS. | `True` | |
| `hsts` | Включает режим HTTP Strict Transport Security (HSTS): заголовок HSTS
добавляется к ответам от проксируемых серверов. Директива `preload` будет включена
в заголовок. | `False` | |
| `hsts-max-age` | Задает значение директивы `max-age` заголовка HSTS. | `2592000` (1 месяц) | |
| `hsts-include-subdomains` | Добавляет директиву `includeSubDomains` в заголовок HSTS. | `False` | |
| `hsts-behind-proxy` | Включает HSTS на основе значения заголовка запроса
`http_x_forwarded_proto`. Следует использовать только в том случае,
если в балансировщике нагрузки (прокси-сервере) перед ANIC
настроена терминация TLS.
#### NOTE
Чтобы управлять перенаправлением с HTTP на HTTPS,
настройте аннотацию `angie.software/redirect-to-https`. | `False` | |
| `ssl-protocols` | Задает значение директивы [ssl_protocols](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-protocols). | `TLSv1 TLSv1.1 TLSv1.2` | |
| `ssl-prefer-server-ciphers` | Включает или отключает директиву [ssl_prefer_server_ciphers](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-prefer-server-ciphers). | `On` | |
| `ssl-ciphers` | Задает значение директивы [ssl_ciphers](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ciphers). | `HIGH:!aNULL:!MD5` | |
| `ssl-dhparam-file` | Задает содержимое файла `dhparam`. Контроллер создаст файл и установит
значение директивы [ssl_dhparam](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-dhparam) с указанием пути к файлу. | Н/Д | |
### Прослушиватели
| Ключ ConfigMap | Описание | По умолчанию | Пример |
|------------------|---------------------------------------------------|----------------|----------|
| `http2` | Включает HTTP/2 на серверах с включенным SSL. | `False` | |
| `proxy-protocol` | Включает прокси-протокол для входящих соединений. | `False` | |
### Бэкенд-сервисы (апстримы)
| Ключ ConfigMap | Описание | По умолчанию | Пример |
|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------|----------|
| `lb-method` | Задает метод балансировки нагрузки. Чтобы использовать циклический
метод, укажите `"round_robin"`. | `"random two least_conn"` | |
| `max-fails` | Задает значение параметра `max_fails` директивы
[server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server). | `1` | |
| `upstream-zone-size` | Задает размер [зоны](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) разделяемой памяти для апстримов. | | |
| `fail-timeout` | Задает значение параметра `fail_timeout` директивы [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server). | `10s` | |
| `keepalive` | Задает значение директивы [keepalive](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive). Обратите внимание: если
значение больше 0, в сгенерированную конфигурацию добавляется
`proxy_set_header Connection "";`. | `0` | |
### Фрагменты и пользовательские шаблоны
| Ключ ConfigMap | Описание | По умолчанию | Пример |
|--------------------------|-------------------------------------------------------------|--------------------------------------------------------|----------|
| `main-snippets` | Задает пользовательский фрагмент в основном контексте. | Н/Д | |
| `http-snippets` | Задает пользовательский фрагмент в контексте http. | Н/Д | |
| `location-snippets` | Задает пользовательский фрагмент в контексте location. | Н/Д | |
| `server-snippets` | Задает пользовательский фрагмент в контексте server. | Н/Д | |
| `stream-snippets` | Задает пользовательский фрагмент в контексте stream. | Н/Д | |
| `main-template` | Задает основной шаблон конфигурации Angie. | По умолчанию шаблон считывается из файла в контейнере. | |
| `ingress-template` | Задает шаблон конфигурации Angie для ресурса Ingress. | По умолчанию шаблон считывается из файла в контейнере. | |
| `virtualserver-template` | Задает шаблон конфигурации Angie для ресурса VirtualServer. | По умолчанию шаблон считывается из файла в контейнере. | |
# https://angie.software/anic/docs/configuration/globalconfiguration-resource.md
# GlobalConfiguration
Ресурс GlobalConfiguration позволяет вам определить глобальные параметры
конфигурации ANIC. Он реализован как [пользовательский ресурс](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
Ресурс поддерживает настройку прослушивателей для балансировки нагрузки TCP и
UDP. Прослушиватели требуются [ресурсам TransportServer](https://angie.software//anic/docs/configuration/transportserver-resource.md#transportserver-resource).
## Предварительные требования
При установке ANIC с манифестами
необходимо указать ссылку на ресурс GlobalConfiguration в аргументе командной
строки [-global-configuration](https://angie.software//anic/docs/configuration/command-line-arguments.md#global-configuration-string).
Для ANIC требуется только один ресурс GlobalConfiguration.
## Спецификация GlobalConfiguration
Ресурс GlobalConfiguration определяет глобальные параметры конфигурации
ANIC. Ниже приведен пример:
```yaml
apiVersion: k8s.angie.software/v1alpha1
kind: GlobalConfiguration
metadata:
name: angie-configuration
namespace: angie-ingress
spec:
listeners:
- name: dns-udp
port: 5353
protocol: UDP
- name: dns-tcp
port: 5353
protocol: TCP
```
| Поле | Описание | Тип | Обязательно |
|-------------|-------------------------|-----------------------------------|---------------|
| `listeners` | Список прослушивателей. | [listener[ ]](#globconf-listener) | Нет |
### Прослушиватель
Прослушиватель определяет комбинацию протокола и порта, которые Angie будет
использовать при приеме трафика для [TransportServer](https://angie.software//anic/docs/configuration/transportserver-resource.md#transportserver-resource):
```yaml
name: dns-tcp
port: 5353
protocol: TCP
```
| Поле | Описание | Тип | Обязательно |
|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `name` | Имя прослушивателя. Это должна быть допустимая метка DNS, как определено в RFC 1035. Например, допустимы значения `hello` и `listener-123`. Имя должно быть уникальным среди всех прослушивателей. Имя `tls-passthrough` зарезервировано для встроенного прослушивателя TLS Passthrough и не может быть использовано. | `string` | Да |
| `port` | Порт прослушивателя. Порт должен находиться в диапазоне `1..65535` со следующими исключениями: `80`, `443`, порт [статуса](/angie-ingress-controller/logging-and-monitoring/status-page). Комбинация порта и протокола должна быть уникальна среди всех прослушивателей. | `int` | Да |
| `protocol` | Протокол прослушивателя. Поддерживаемые значения: `TCP` и `UDP`. | `string` | Да |
## Использование GlobalConfiguration
Вы можете использовать обычные команды `kubectl` для работы с ресурсом
GlobalConfiguration.
Например, следующая команда создает ресурс GlobalConfiguration,
определенный в `global-configuration.yaml` с именем
`angie-configuration`:
```default
$ kubectl apply -f global-configuration.yaml
globalconfiguration.k8s.angie.software/angie-configuration created
```
Предполагая, что пространство имен ресурса называется `angie-ingress`,
вы можете получить ресурс, запустив:
```default
$ kubectl get globalconfiguration angie-configuration -n angie-ingress
NAME AGE
angie-configuration 13s
```
В kubectl get и подобных командах также можно использовать короткое имя
`gc` вместо `globalconfiguration`.
### Валидация
Для ресурса GlobalConfiguration доступны два типа валидации:
- *Структурная валидация* с помощью `kubectl` и сервера Kubernetes
API.
- *Всесторонняя валидация* с помощью ANIC.
#### Структурная валидация
Пользовательское определение ресурса для GlobalConfiguration включает
структурную схему OpenAPI, которая описывает тип каждого поля ресурса.
Если вы попытаетесь создать (или обновить) ресурс с нарушением
структурной схемы (например, используете строковое значение для поля
порта прослушивателя), `kubectl` и сервер Kubernetes API отклонят
такой ресурс:
- Пример проверки `kubectl`:
```default
$ kubectl apply -f global-configuration.yaml
error: error validating "global-configuration.yaml": error validating
data: ValidationError(GlobalConfiguration.spec.listeners[0].port):
invalid type for
software.angie.k8s.v1alpha1.GlobalConfiguration.spec.listeners.port:
got "string", expected "integer"; if you choose to ignore these
errors, turn validation off with --validate=false
```
- Пример проверки сервера API Kubernetes:
```default
$ kubectl apply -f global-configuration.yaml --validate=false
The GlobalConfiguration "angie-configuration" is invalid: []: Invalid
value: map[string]interface {}{ ... }: validation failure list:
spec.listeners.port in body must be of type integer: "string"
```
Если ресурс не отклонен (то есть не нарушает структурную схему), ANIC
проверит его дополнительно.
#### Всесторонняя валидация
ANIC проверяет поля ресурса GlobalConfiguration. Если
ресурс недопустим, ANIC не будет его использовать.
Рассмотрим следующие два случая:
1. Если при запуске пода ANIC ресурс GlobalConfiguration
недопустим, ANIC не сможет запуститься и завершит
работу с ошибкой.
2. Если ресурс GlobalConfiguration становится недействительным, когда
ANIC запущен, то ANIC проигнорирует новую
версию. Он сообщит об ошибке и продолжит использовать предыдущую
версию. Когда ресурс снова станет действительным, ANIC
начнет его использовать.
#### NOTE
Если ресурс GlobalConfiguration был удален во время
работы ANIC, тот продолжит использовать предыдущую версию ресурса.
Вы можете проверить, успешно ли ANIC применил конфигурацию
для GlobalConfiguration. Для нашего ресурса GlobalConfiguration
`angie-configuration` мы можем запустить:
```default
$ kubectl describe gc angie-configuration -n angie-ingress
. . .
Events:
Type Reason Age From Message
Normal Updated 11s angie-ingress-controller GlobalConfiguration
angie-ingress/angie-configuration was updated
```
Обратите внимание, что раздел "События" (Events) включает событие Normal с
причиной Updated, которое информирует нас о том, что конфигурация была успешно
применена.
Если вы создадите недопустимый ресурс, ANIC отклонит его и выдаст событие
Rejected. Например, если вы создадите ресурс GlobalConfiguration
angie-configuration с несколькими прослушивателями, для которых задан один и
тот же протокол UDP и порт 53, вы получите:
```default
$ kubectl describe gc angie-configuration -n angie-ingress
. . .
Events:
Type Reason Age From Message
Normal Updated 55s angie-ingress-controller GlobalConfiguration
angie-ingress/angie-configuration was updated
Warning Rejected 6s angie-ingress-controller GlobalConfiguration
angie-ingress/angie-configuration is invalid and was rejected:
spec.listeners: Duplicate value: "Duplicated port/protocol combination
53/UDP"
Обратите внимание, что раздел "События" (Events) включает предупреждающее
событие с указанием причины отклонения.
```
# https://angie.software/anic/docs/configuration/policy-resource.md
# Policy
Ресурс Policy позволяет настраивать такие функции, как контроль доступа и
ограничение скорости; их можно добавить к вашим [ресурсам VirtualServer и
VirtualServerRoute](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserver-and-virtualserverroute-resources).
Он реализован как [пользовательский ресурс](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
Это справочная документация по ресурсу Policy.
## Предварительные требования
Политики работают совместно [с ресурсами VirtualServer и VirtualServerRoute](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserver-and-virtualserverroute-resources),
которые необходимо создавать отдельно.
## Спецификация Policy
Ниже приведен пример политики, которая разрешает доступ клиентам из
подсети `10.0.0.0/8` и запрещает доступ любым другим:
```yaml
apiVersion: k8s.angie.software/v1
kind: Policy
metadata:
name: allow-localhost
spec:
accessControl:
allow:
- 10.0.0.0/8
```
| Поле | Описание | Тип | Обязательно |
|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------|---------------|
| `AccessControl` | Политика контроля доступа, основанная на IP-адресе клиента. | [AccessControl](#accesscontrol) | Нет |
| `ingressClassName` | Указывает, какой экземпляр ANIC должен обрабатывать ресурс Policy. | `string` | Нет |
| `rateLimit` | Политика ограничения скорости управляет скоростью обработки запросов по определенному ключу. | [RateLimit](#ratelimit) | Нет |
| `basicAuth` | Политика базовой аутентификации настраивает в Angie аутентификацию клиентских запросов с использованием базовой аутентификации HTTP по учетным данным. | [BasicAuth](#basicauth) | Нет |
| `ingressMTLS` | Политика IngressMTLS настраивает проверку сертификата клиента. | [IngressMTLS](#ingressmtls) | Нет |
| `egressMTLS` | Политика EgressMTLS настраивает аутентификацию и проверку сертификата апстрима. | [EgressMTLS](#egressmtls) | Нет |
| `OIDC` | Политика OIDC настраивает аутентификацию через провайдера OIDC. | [OIDC](#oidc-policy) | Нет |
| `JWT` | Политика JWT настраивает Angie для аутентификации запросов клиентов с использованием JSON Web Tokens. | [JWT](#jwt-policy) | Нет |
#### NOTE
Политика должна включать в себя ровно одно значение.
### AccessControl
Политика контроля доступа настраивает в Angie отклонение или принятие
запросов от клиентов с указанными IP-адресами и подсетями.
Например, следующая политика разрешает доступ клиентам из подсети
`10.0.0.0/8` и запрещает доступ любым другим:
```yaml
accessControl:
allow:
- 10.0.0.0/8
```
Напротив, приведенная ниже политика делает обратное: запрещает доступ
клиентам с `10.0.0.0/8` и разрешает доступ любым другим клиентам:
```yaml
accessControl:
deny:
- 10.0.0.0/8
```
#### NOTE
Функция реализована с использованием модуля Angie [http_access](https://angie.software//angie/docs/configuration/modules/http/http_access.md#http-access). Политика контроля доступа ANIC поддерживает либо
разрешающие, либо запрещающие правила, но не оба вида сразу (в отличие от
модуля).
| Поле | Описание | Тип | Обязательно |
|---------|--------------------------------------------------------------------------------------------------|-------------|---------------|
| `allow` | Разрешает доступ для указанных сетей или адресов.
Например, `192.168.1.1` или `10.1.1.0/16`. | `string[ ]` | Нет |
| `deny` | Запрещает доступ для указанных сетей или адресов.
Например, `192.168.1.1` или `10.1.1.0/16`. | `string[ ]` | Нет |
AccessControl должен включать либо `allow`, либо `deny`.
#### Поведение слияния AccessControl
Ресурс VirtualServer или VirtualServerRoute может ссылаться на несколько
политик контроля доступа. Например, здесь мы ссылаемся на две политики,
в каждой из которых настроен список разрешений:
```yaml
policies:
- name: allow-policy-one
- name: allow-policy-two
```
Когда вы ссылаетесь на несколько политик контроля доступа, ANIC
объединит их содержимое в один список разрешений или запретов.
Ссылки как на разрешающие, так и на запрещающие политики, как показано в
примере ниже, не поддерживаются. Если указаны ссылки как на разрешающие,
так и на запрещающие списки, ANIC использует только
политики разрешающих списков.
```yaml
policies:
- name: deny-policy
- name: allow-policy-one
- name: allow-policy-two
```
#### RateLimit
Политика ограничения скорости настраивает в Angie ограничение скорости
обработки запросов.
Например, следующая политика ограничит все последующие запросы,
поступающие с одного IP-адреса, при превышении скорости в 10 запросов в
секунду:
```yaml
rateLimit:
rate: 10r/s
zoneSize: 10M
key: ${binary_remote_addr}
```
#### NOTE
Функция реализована с использованием модуля Angie
[Limit Req](https://angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req).
| Поле | Описание | Тип | Обязательно |
|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `rate` | Допустимая скорость запросов. Скорость указывается в запросах в секунду (r/s) или запросах в минуту (r/m). | `string` | Да |
| `key` | Ключ, к которому применяется ограничение скорости. Может содержать текст, переменные или их комбинацию. Переменные должны заключены в `${}`. Например: `$*binary_remote_addr*`. Допустимые переменные: `$binary_remote_addr`, `$request_uri`, `$url`, `$http_`, `$args`, `$arg_`, `$cookie_`. | `string` | Да |
| `zoneSize` | Размер зоны разделяемой памяти. Допускаются только положительные значения. Допустимые суффиксы - `k` или `m`; если суффикс не задан, предполагается `k`. | `string` | Да |
| `delay` | Указывает предел, при достижении которого избыточные запросы становятся отложенными. Если этот параметр не задан, задерживаются все избыточные запросы. | `int` | Нет |
| `noDelay` | Отключает задержку избыточных запросов при ограничении количества запросов. Имеет приоритет над `delay`, если заданы оба параметра. | `bool` | Нет |
| `burst` | Избыточные запросы задерживаются до тех пор, пока их количество не превысит размер `burst`, после чего запрос завершается с ошибкой. | `int` | Нет |
| `dryRun` | Включает режим сухого прогона. В этом режиме ограничение скорости фактически не применяется, но количество избыточных запросов учитывается, как обычно, в зоне разделяемой памяти. | `bool` | Нет |
| `logLevel` | Устанавливает желаемый уровень ведения журнала для случаев, когда сервер отказывается обрабатывать запросы из-за превышения скорости или задерживает обработку запросов. Допустимые значения: `info`, `notice`, `warn` или `error`. Значение по умолчанию - `error`. | `string` | Нет |
| `rejectCode` | Задает код состояния, возвращаемый в ответ на отклоненные запросы. Значение должно попадать в диапазон `400..599`. Значение по умолчанию - `503`. | `int` | Нет |
Для каждой политики, на которую ссылается VirtualServer или его
VirtualServerRoute, ANIC сгенерирует единую зону ограничения
скорости, определенную директивой [limit_req_zone](https://angie.software//angie/docs/configuration/modules/http/http_limit_req.md#limit-req-zone). Если два
ресурса VirtualServer ссылаются на одну и ту же политику, ANIC
сгенерирует две разные зоны ограничения скорости, по одной на каждый
VirtualServer.
#### Поведение слияния RateLimit
Ресурс VirtualServer или VirtualServerRoute может ссылаться на несколько
политик ограничения скорости. Например, здесь мы ссылаемся на две
политики:
```yaml
policies:
- name: rate-limit-policy-one
- name: rate-limit-policy-two
```
Когда вы ссылаетесь на несколько политик ограничения скорости, ANIC
настроит в Angie использование всех указанных ограничений
скорости. Если определено несколько политик, каждая дополнительная
политика наследует параметры `dryRun`, `LogLevel` и `rejectCode`
из первой политики, на которую идет ссылка (`rate-limit-policy-one` в
примере выше).
### BasicAuth
Настраивает в Angie аутентификацию клиентских запросов при помощи [базовой
схемы аутентификации HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
Например, следующая политика будет отклонять все запросы, которые не
содержат действительную комбинацию имени пользователя и пароля в
заголовке HTTP `Authentication`
```yaml
basicAuth:
secret: htpasswd-secret
realm: "My API"
```
#### NOTE
Функция реализована с использованием модуля Angie [Auth Basic](https://angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic).
| Поле | Описание | Тип | Обязательно |
|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `secret` | Имя секрета Kubernetes, в котором хранится конфигурация Htpasswd. Он должен находиться в том же пространстве имен, что и ресурс Policy. Секрет должен иметь тип `angie.software/htpasswd`, а конфигурация должна храниться в секрете по ключу `htpasswd`; в противном случае секрет будет отклонен как недействительный. | `string` | Да |
| `realm` | Область для базовой аутентификации. | `string` | Нет |
#### Поведение слияния BasicAuth
Ресурс VirtualServer или VirtualServerRoute может ссылаться на несколько
политик базовой аутентификации. При этом будет применяться только одна
из них. Все последующие ссылки будут проигнорированы. Например, здесь мы
ссылаемся на две политики:
```yaml
policies:
- name: basic-auth-policy-one
- name: basic-auth-policy-two
```
В этом примере ANIC будет использовать конфигурацию из
первой ссылки на политику "basic-auth-policy-one" и игнорирует
"basic-auth-policy-two".
### IngressMTLS
Политика IngressMTLS настраивает проверку сертификата клиента.
Например, следующая политика будет проверять сертификат клиента,
используя сертификат Центра Сертификации, указанный в `ingress-mtls-secret`:
```yaml
ingressMTLS:
clientCertSecret: ingress-mtls-secret
verifyClient: "on"
verifyDepth: 1
```
Ниже приведен пример `ingress-mtls-secret` типа `angie.software/ca`
```yaml
kind: Secret
metadata:
name: ingress-mtls-secret
apiVersion: v1
type: angie.software/ca
data:
ca.crt:
```
У ресурса VirtualServer, который ссылается на политику IngressMTLS,
должно быть следующие настройки:
- включена [терминация TLS](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#virtualservertls).
- ссылка на политику в
[спецификации VirtualServer](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserver-spec).
Не разрешается ссылаться на политику IngressMTLS в
[маршруте](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserverroute)
или
[вложенном маршруте](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserverroutesubroute)
VirtualServerRoute.
Если эти условия нарушены, Angie будет отправлять клиентам код состояния
`500`.
Вы можете передавать сведения о сертификате клиента, включая сам
сертификат, серверам апстрима. Например:
```yaml
action:
proxy:
upstream: webapp
requestHeaders:
set:
- name: client-cert-subj-dn
value: ${ssl_client_s_dn} # subject DN
- name: client-cert
value: ${ssl_client_escaped_cert} # клиентский сертификат в формате PEM (urlencoded)
```
Мы используем параметр `requestHeaders` в [Action.Proxy](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#actionproxy)
для задания значений двух заголовков, которые Angie будет передавать серверам
апстрима. См. список встроенных переменных, поддерживаемых модулем
[SSL](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#http-ssl), которые вы можете использовать для передачи сведений о
сертификате клиента.
#### NOTE
Функция реализована с использованием модуля Angie [SSL](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#http-ssl).
#### Использование списка отзыва сертификатов
Политика IngressMTLS поддерживает настройку списка CRL для политики. Это
можно сделать одним из двух способов.
#### NOTE
Одновременно можно использовать только один из этих параметров конфигурации.
1. Добавление в тип секрета `angie.software/ca`поля `ca.crl`,
которое содержит список отзыва сертификатов в кодировке base64.
Пример YAML:
```yaml
kind: Secret
metadata:
name: ingress-mtls-secret
apiVersion: v1
type: angie.software/ca
data:
ca.crt:
ca.crl:
```
2. Добавление поля `crlFileName` с именем CRL-файла в спецификацию
политики IngressMTLS.
#### NOTE
Этот параметр конфигурации следует использовать только при наличии
CRL-файла размером более 1 МБ; в противном случае рекомендуется
использовать для управления CRL тип секрета `angie.software/ca`.
Пример YAML:
```yaml
apiVersion: k8s.angie.software/v1
kind: Policy
metadata:
name: ingress-mtls-policy
spec:
ingressMTLS:
clientCertSecret: ingress-mtls-secret
crlFileName: webapp.crl
verifyClient: "on"
verifyDepth: 1
```
#### WARNING
При настройке CRL с помощью поля `ingressMTLS.crlFileName` следует
учитывать дополнительный контекст:
1. ANIC ожидает, что CRL, в данном случае `webapp.crl`,
будет находиться в каталоге `/etc/angie/secrets`. Для развертывания
ANIC необходимо будет добавить точку подключения тома.
Добавьте свой CRL в каталог `/etc/angie/secrets`.
2. При обновлении содержимого списка CRL (например, был отозван новый
сертификат) Angie необходимо перезагрузить, чтобы отразились
последние изменения. В зависимости от вашей среды для этого может
потребоваться обновить имя списка CRL и применить это обновление к
политике `ingress-mtls.yaml`, чтобы Angie получил последнюю версию
CRL.
Обратитесь к документации Kubernetes по
[томам](https://kubernetes.io/docs/concepts/storage/volumes/), чтобы
найти наилучшую реализацию для вашей среды.
| Поле | Описание | Тип | Обязательно |
|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `clientCertSecret` | Имя секрета Kubernetes, в котором хранится сертификат центра сертификации. Он должен находиться в том же пространстве имен, что и ресурс Policy. Секрет должен иметь тип `angie.software/ca`, а конфигурация должна храниться в секрете по ключу `ca.crt`; в противном случае секрет будет отклонен как недействительный. | `string` | Да |
| `verifyClient` | Верификация для клиента. Допустимые значения: `"on"`, `"off"`, `"optional"`, `"optional_no_ca"`. Значение по умолчанию - `"on"`. | `string` | Нет |
| `verifyDepth` | Устанавливает глубину проверки в цепочке клиентских сертификатов. Значение по умолчанию равно `1`. | `int` | Нет |
| `crlFileName` | Имя файла списка отзыва сертификатов. ANIC будет искать этот файл в каталоге /etc/angie/secrets | `string` | Нет |
#### Поведение слияния IngressMTLS
Ресурс VirtualServer может ссылаться только на одну политику
IngressMTLS. Все последующие ссылки будут проигнорированы. Например,
здесь мы ссылаемся на две политики:
```yaml
policies:
- name: ingress-mtls-policy-one
- name: ingress-mtls-policy-two
```
В этом примере ANIC будет использовать конфигурацию из
первой ссылки на политику `ingress-mtls-policy-one` и игнорирует
`ingress-mtls-policy-two`.
### EgressMTLS
EgressMTLS настраивает аутентификацию и проверку сертификатов для
апстримов.
Например, следующая политика будет использовать `egress-mtls-secret`
для аутентификации в приложении апстрима и `egress-trusted-ca-secret`
для проверки сертификата приложения:
```yaml
egressMTLS:
tlsSecret: egress-mtls-secret
trustedCertSecret: egress-trusted-ca-secret
verifyServer: on
verifyDepth: 2
```
#### NOTE
Функция реализована с использованием модуля Angie [Proxy](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy).
| Поле | Описание | Тип | Обязательно |
|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `tlsSecret` | Имя секрета файла Kubernetes, в котором хранятся сертификат и ключ TLS. Он должен находиться в том же пространстве имен, что и ресурс Policy. Секрет должен иметь тип `kubernetes.io/tls`, сертификат - храниться в секрете под ключом `tls.crt`, а ключ - как `tls.key`; в противном случае секрет будет отклонен как недействительный. | `string` | Нет |
| `trustedCertSecret` | Имя секрета Kubernetes, в котором хранится сертификат центра сертификации. Он должен находиться в том же пространстве имен, что и ресурс Policy. Секрет должен иметь тип `angie.software/ca`, а конфигурация должна храниться в секрете по ключу `ca.crt`; в противном случае секрет будет отклонен как недействительный. | `string` | Нет |
| `verifyServer` | Включает проверку сертификата HTTPS-сервера апстрима. | `bool` | Нет |
| `verifyDepth` | Устанавливает глубину проверки в цепочке сертификатов проксируемого HTTPS-сервера. Значение по умолчанию равно `1`. | `int` | Нет |
| `sessionReuse` | Позволяет повторно использовать SSL-сеансы к апстримам. Значение по умолчанию равно `true`. | `bool` | Нет |
| `serverName` | Позволяет передавать имя сервера через расширение `SNI`. | `bool` | Нет |
| `sslName` | Позволяет переопределить имя сервера, используемое для проверки сертификата HTTPS-сервера апстрима. | `string` | Нет |
| `ciphers` | Указывает разрешенные шифры для запросов к HTTPS-серверу апстрима. Значение по умолчанию - `DEFAULT`. | `string` | Нет |
| `protocols` | Задает протоколы для запросов к HTTPS-серверу апстрима. Значение по умолчанию - `TLSv1, TLSv1.1, TLSv1.2`. | `string` | Нет |
#### Поведение слияния EgressMTLS
Ресурс VirtualServer или VirtualServerRoute может ссылаться на несколько
политик EgressMTLS. При этом будет применяться только одна из них. Все
последующие ссылки будут проигнорированы. Например, здесь мы ссылаемся
на две политики:
```yaml
policies:
- name: egress-mtls-policy-one
- name: egress-mtls-policy-two
```
В этом примере ANIC будет использовать конфигурацию из
первой ссылки на политику `egress-mtls-policy-one` и игнорирует
`egress-mtls-policy-two`.
### OIDC
OIDC (OpenID Connect) обеспечивает удобную аутентификацию пользователей через внешнего провайдера, используя безопасные токены для управления доступом в системе.
#### NOTE
Эта функция отключена по умолчанию. Чтобы ее включить, задайте аргумент командной строки `enable-oidc=true`.
Политика OIDC настраивает ANIC как клиент (relying party) для аутентификации через OpenID Connect:
```yaml
policies:
- name: oidc-policy
```
Например, следующая конфигурация использует clientID `myclient` и clientSecret `oidc-secret` для аутентификации через провайдера OpenID Connect `https://idp.example.com`:
```yaml
oidc:
clientID: myclient
clientSecret: oidc-secret
authEndpoint: https://idp.example.com/openid-connect/auth
jwksURI: https://idp.example.com/openid-connect/certs
tokenEndpoint: https://idp.example.com/openid-connect/token
scope: openid+profile+email
accessTokenEnable: true
```
Обязательные условия:
- В спецификации VirtualServer задайте обязательные
переменные `$jwt_claim_iat`, `$jwt_claim_iss`, `$jwt_claim_sub`, `$jwt_claim_aud` в [maps](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserver-maps). Переменные обеспечивают валидацию токенов в процессе аутентификации OIDC.
- Добавьте секрет с ключом клиента. Ключ должен быть закодирован в Base64:
> ```yaml
> apiVersion: v1
> kind: Secret
> metadata:
> name: oidc-secret
> type: angie.software/oidc
> data:
> client-secret:
> ```
Пошаговые инструкции по настройке см. в статье [Настройка OIDC](https://angie.software//anic/docs/custom-resources/configuring-oidc.md#configuring-oidc).
| Поле | Описание | Тип | Обязательно |
|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `clientID` | Идентификатор клиента, предоставленный провайдером OIDC. Идентифицирует приложение,
которое обращается за авторизацией. | `string` | да |
| `clientSecret` | Имя секрета, где хранится ключ клиента. Должен находиться в том же пространстве имен, что и Policy. | `string` | да |
| `authEndpoint` | URL конечной точки авторизации, предоставленной провайдером OIDC. Это адрес, по которому
будут отправляться запросы для аутентификации пользователя. | `string` | да |
| `jwksURI` | URI, по которому провайдер OIDC предоставляет сертификаты (JSON Web Key Set)
для проверки выданных сервером JWT-токенов (JSON Web Token). | `string` | да |
| `tokenEndpoint` | URL для получения токенов аутентификации и обновления от провайдера OIDC. | `string` | да |
| `scope` | Список OIDC-областей, которые нужно запросить у провайдера. Значение по умолчанию - `openid`. Это значение является обязательным. Вы также можете добавлять другие области, используя знак +, например: `openid+profile+email`. | `string` | да |
| `accessTokenEnable` | Включает использование Bearer-токена для авторизации доступа к защищенным ресурсам на проксируемом сервере. | `bool` | нет |
#### NOTE
В ресурсах VirtualServer можно использовать только одну политику OIDC, причем ее можно применять к разным маршрутам VirtualServer. Например, если в конфигурации есть несколько маршрутов для обработки запросов, все они могут использовать одну и ту же политику OIDC для аутентификации пользователей.
#### Поведение слияния OIDC
Ресурс VirtualServer может ссылаться на несколько
политик OIDC. При этом будет применяться только одна из них. Все
последующие ссылки будут проигнорированы. Например, здесь мы ссылаемся
на две политики:
```yaml
policies:
- name: oidc-policy-one
- name: oidc-policy-two
```
В этом примере ANIC будет использовать конфигурацию из
первой ссылки на политику `oidc-policy-one` и игнорирует `oidc-policy-two`.
### JWT
Политика JWT настраивает в Angie аутентификацию запросов клиентов с использованием JSON Web Tokens.
```yaml
policies:
- name: jwt-policy
```
#### NOTE
Эта функция отключена по умолчанию. Чтобы ее включить, задайте аргумент командной строки `-enable-jwt=true`.
Следующая политика будет отклонять все запросы, которые не содержат действительный JWT в токене заголовка HTTP:
```yaml
jwt:
realm: MyProductAPI
secret: jwk-secret
token: $http_token
```
Обязательные условия:
- Добавьте секрет с ключом клиента. Ключ должен быть закодирован в Base64:
> ```yaml
> apiVersion: v1
> kind: Secret
> metadata:
> name: jwk-secret
> type: angie.software/jwk
> data:
> jwk:
> ```
| Поле | Описание | Тип | Обязательно |
|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `realm` | Область, которую клиент увидит при запросе аутентификации, например, строка, описывающая защищенный ресурс. | `string` | да |
| `secret` | Имя секрета Kubernetes, который хранит JSON Web Key (JWK), используемый для проверки подписей токенов JWT. Angie будет использовать ключи из этого секрета для валидации подписей JWT и проверки их подлинности. Секрет должен находиться в том же пространстве имен, что и Policy. | `string` | да |
| `token` | Указывает, откуда нужно извлечь JWT. Например, переменная `$http_token` ссылается на значение заголовка `HTTP token`, который будет передан клиентом. | `string` | нет |
#### Поведение слияния JWT
Ресурс VirtualServer может ссылаться на несколько
политик JWT. При этом будет применяться только одна из них. Все
последующие ссылки будут проигнорированы. Например, здесь мы ссылаемся
на две политики:
```yaml
policies:
- name: jwt-policy-one
- name: jwt-policy-two
```
В этом примере ANIC будет использовать конфигурацию из
первой ссылки на политику `jwt-policy-one` и игнорирует `jwt-policy-two`.
### Применение политик
Политики можно применять как к ресурсам VirtualServer, так и к
VirtualServerRoute. Например:
```yaml
- VirtualServer:
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: cafe
namespace: cafe
spec:
host: cafe.example.com
tls:
secret: cafe-secret
policies: # spec policies
- name: policy1
upstreams:
- name: coffee
service: coffee-svc
port: 80
routes:
- path: /tea
policies: # route policies
- name: policy2
namespace: cafe
route: tea/tea
- path: /coffee
policies: # route policies
- name: policy3
namespace: cafe
action:
pass: coffee
```
В случае VirtualServer политику можно применить:
- для всех маршрутов (политики спецификации)
- к определенному маршруту (политики маршрутов)
Политики маршрутов имеют приоритет над политиками спецификации *того
же типа*. Если в примере выше тип политик `policy-1` и `policy-3`
- `AccessControl`, то для запросов к `cafe.example.com/coffee`
Angie применит `policy-3`.
Переопределение обеспечивается Angie: политики спецификации
реализуются в контексте конфигурации `server`, а политики маршрутов
реализуются в контексте `location`. В результате приоритет в рамках
одного типа имеют политики маршрутов.
- Ресурс VirtualServerRoute, на который ссылается указанный выше
VirtualServer:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServerRoute
metadata:
name: tea
namespace: tea
spec:
host: cafe.example.com
upstreams:
- name: tea
service: tea-svc
port: 80
subroutes: # subroute policies
- path: /tea
policies:
- name: policy4
namespace: tea
action:
pass: tea
```
В VirtualServerRoute можно применить политику к вложенному маршруту
(политики вложенных маршрутов).
Политики вложенных маршрутов имеют приоритет над политиками
спецификации того же типа. В приведенном выше примере, если тип
политик `policy-1` (в VirtualServer) и `policy-4` -
`AccessControl`, то для запросов к `cafe.example.com/tea` Angie
будет применять `policy-4`. Как и в случае с VirtualServer,
переопределение обеспечивается средствами Angie.
Политики вложенных маршрутов всегда имеют приоритет над политиками
маршрутов независимо от типа. Например, политика `policy-2` в
маршруте VirtualServer будет проигнорирована на вложенном маршруте
`/tea`, поскольку у того есть свои собственные политики (в нашем
случае это только `policy4`). Если бы у вложенного маршрута не было
политик, то была бы применена `policy-2`. Это переопределение
выполняет ANIC - контекст `location` для вложенного
маршрута будет содержать либо политики маршрута, либо политики
вложенного маршрута, но не то и другое вместе.
### Недопустимые политики
Angie будет рассматривать политику как недействительную, если
выполняется одно из следующих условий:
- Политика не проходит [всестороннюю валидацию](#comprehensive-validation).
- Политика отсутствует в кластере.
- Политика не соответствует требованиям, предъявляемым к ее конкретному
типу. Например, `политика ingressMTLS` требует, чтобы в
VirtualServer была включена терминация TLS.
В случае недопустимой политики Angie возвращает код состояния 500 для
клиентских запросов со следующими правилами:
- Если на политику ссылается `маршрут` VirtualServer или
`вложенный маршрут` VirtualServerRoute, Angie будет возвращать код
состояния 500 для запросов к URI такого маршрута.
- Если ссылка на политику задана в `спецификации` VirtualServer,
Angie будет возвращать код состояния 500 для запросов ко всем URI
этого VirtualServer.
Если политика недействительна, VirtualServer или VirtualServerRoute будет иметь
статус с предупреждением о состоянии и сообщением, объясняющим, почему
политика не была признана недействительной.
### Валидация
Для ресурса Policy доступны два типа валидации:
- *Структурная валидация* с помощью `kubectl` и сервера Kubernetes API.
- *Всесторонняя валидация* с помощью ANIC.
#### Структурная валидация
Пользовательское определение ресурса для Policy включает структурную схему
OpenAPI, которая описывает тип каждого поля ресурса.
Если вы попытаетесь создать (или обновить) ресурс, который нарушает структурную
схему (например, использует строковое значение вместо массива строк в поле
`allow`), то `kubectl` и сервер Kubernetes API отклонят ресурс.
- Пример проверки `kubectl`:
```console
kubectl apply -f access-control-policy-allow.yaml
error: error validating "access-control-policy-allow.yaml": error validating data: ValidationError(Policy.spec.accessControl.allow): invalid type for software.angie.k8s.v1.Policy.spec.accessControl.allow: got "string", expected "array"; if you choose to ignore these errors, turn validation off with --validate=false
```
- Пример проверки сервера Kubernetes API:
```console
kubectl apply -f access-control-policy-allow.yaml --validate=false
The Policy "webapp-policy" is invalid: spec.accessControl.allow: Invalid value: "string": spec.accessControl.allow in body must be of type array: "string"
```
Если ресурс прошел структурную валидацию, выполняется всесторонняя валидация
ANIC.
#### Всесторонняя валидация
ANIC проверяет поля ресурса Policy. Если ресурс недопустим,
ANIC отклонит его. Ресурс останется в кластере, но ANIC
будет игнорировать его.
Можно использовать `kubectl`, чтобы проверить, успешно ли ANIC
применил конфигурацию Policy. Для политики `mypolicy` мы можем запустить:
```console
kubectl describe pol mypolicy
. . .
Events:
Type Reason Age From Message
-----
Normal AddedOrUpdated 11s angie-ingress-controller Policy default/mypolicy was added or updated
```
Обратите внимание, что раздел "События" (Events) включает событие Normal с
причиной AddedOrUpdated, которое информирует нас о том, что конфигурация была
успешно применена.
Если вы создадите недопустимый ресурс, ANIC отклонит его и выдаст
событие Rejected. Например, если вы создадите политику `mypolicy` с
недопустимым IP-адресом `10.0.0.` в поле `allow`, то вы получите:
```console
kubectl describe policy mypolicy
. . .
Events:
Type Reason Age From Message
-----
Warning Rejected 7s angie-ingress-controller Policy default/mypolicy is invalid and was rejected: spec.accessControl.allow[0]: Invalid value: "10.0.0.": must be a CIDR or IP
```
Обратите внимание, что раздел "События" (Events) включает предупреждающее
событие с указанием причины отклонения.
Кроме того, эта информация также доступна в поле `status` ресурса Policy.
Обратите внимание на раздел "Статус" (Status) политики:
```console
kubectl describe pol mypolicy
. . .
Status:
Message: Policy default/mypolicy is invalid and was rejected: spec.accessControl.allow[0]: Invalid value: "10.0.0.": must be a CIDR or IP
Reason: Rejected
State: Invalid
```
#### NOTE
Если вы сделаете существующий ресурс недействительным,
ANIC отклонит его.
# https://angie.software/anic/docs/configuration/transportserver-resource.md
# TransportServer
* **og:description:**
Ресурс TransportServer для настройки балансировки нагрузки TCP, UDP и TLS Passthrough в ANIC
Ресурс TransportServer позволяет настраивать балансировку нагрузки по
протоколам TCP, UDP и TLS Passthrough. Он реализован как [пользовательский
ресурс](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
Это справочная документация по ресурсу TransportServer.
## Предварительные требования
- Для TCP и UDP ресурс TransportServer должен использоваться совместно с
ресурсом GlobalConfiguration, который должен быть создан отдельно.
- Для TLS Passthrough обязательно включите параметр командной строки
`-enable-tls-passthrough` в ANIC.
## Спецификация TransportServer
Ресурс TransportServer определяет конфигурацию балансировки нагрузки для
трафика TCP, UDP или TLS Passthrough. Ниже приведено несколько примеров:
- Балансировка нагрузки TCP:
```yaml
apiVersion: k8s.angie.software/v1alpha1
kind: TransportServer
metadata:
name: dns-tcp
spec:
listener:
name: dns-tcp
protocol: TCP
tls:
secret: cafe-secret
upstreams:
- name: dns-app
service: dns-service
port: 5353
action:
pass: dns-app
```
- Балансировка нагрузки UDP:
```yaml
apiVersion: k8s.angie.software/v1alpha1
kind: TransportServer
metadata:
name: dns-udp
spec:
listener:
name: dns-udp
protocol: UDP
upstreams:
- name: dns-app
service: dns-service
port: 5353
upstreamParameters:
udpRequests: 1
udpResponses: 1
action:
pass: dns-app
```
- Балансировка нагрузки TLS Passthrough:
```yaml
apiVersion: k8s.angie.software/v1alpha1
kind: TransportServer
metadata:
name: secure-app
spec:
listener:
name: tls-passthrough
protocol: TLS_PASSTHROUGH
host: app.example.com
upstreams:
- name: secure-app
service: secure-app
port: 8443
action:
pass: secure-app
```
| Поле | Описание | Тип | Обязательно |
|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|---------------|
| `listener` | Прослушиватель, через который Angie будет принимать входящие соединения и датаграммы. | [Listener](#listener) | Да |
| `host` | Хост (доменное имя) сервера. Это должен быть допустимый поддомен, как определено в RFC 1123, например `my-app` или `hello.example.com`. Домены с подстановочными знаками, такие как `*.example.com`, не допускаются. Требуется для балансировки нагрузки TLS Passthrough. | `string` | Нет |
| `tls` | Конфигурация терминации TLS. Не поддерживается для балансировки нагрузки TLS Passthrough. | [TLS](#tls) | Нет |
| `upstreams` | Список апстримов. | [upstream[ ]](#upstream) | Да |
| `upstreamParameters` | Параметры апстрима. | [UpstreamParameters](#upstreamparameters) | Нет |
| `action` | Действие, выполняемое для клиентского соединения или датаграммы. | [Action](#action) | Да |
| `ingressClassName` | Указывает, какой экземпляр ANIC должен обрабатывать ресурс TransportServer. | `string` | Нет |
| `streamSnippets` | Задает пользовательский фрагмент в контексте `stream`. | `string` | Нет |
| `serverSnippets` | Задает пользовательский фрагмент в контексте `server`. | `string` | Нет |
### Listener
Ссылается на прослушиватель, через который Angie будет принимать входящий
трафик к TransportServer. Для TCP и UDP прослушиватель должен быть определен в
ресурсе GlobalConfiguration.
При ссылке на прослушиватель должны совпадать как имя, так и протокол. Для TLS
Passthrough используйте встроенный прослушиватель с именем `tls-passthrough`
и протоколом `TLS_PASSTHROUGH`.
Пример:
```yaml
listener:
name: dns-udp
protocol: UDP
```
| Поле | Описание | Тип | Обязательно |
|------------|--------------------------|----------|---------------|
| `name` | Имя прослушивателя. | `string` | Да |
| `protocol` | Протокол прослушивателя. | `string` | Да |
### TLS
Поле tls определяет конфигурацию TLS для TransportServer. Обратите внимание,
что текущая реализация поддерживает терминацию TLS на нескольких портах, где
каждому приложению принадлежит выделенный порт. При этом ANIC
терминирует TLS-соединения на каждом порту, где каждое приложение использует свой
собственный сертификат или ключ, и направляет соединения соответствующему
приложению (сервису) на основе этого входящего порта (т. е. любое
TLS-соединение независимо от настроек SNI на порту будет перенаправлено в
приложение, соответствующее этому порту).
Пример конфигурации показан ниже:
```yaml
secret: cafe-secret
```
| Поле | Описание | Тип | Обязательно |
|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `secret` | Имя секрета с сертификатом TLS и ключом. Секрет должен принадлежать тому же
пространству имен, что и транспортный сервер. Секрет должен иметь тип
`kubernetes.io/tls` и содержать ключи с именами `tls.crt` и
`tls.key`, содержащие сертификат и закрытый ключ, как описано
[здесь](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). | `string` | Нет |
### Upstream
Определяет конечное место назначения для TransportServer. Например:
```yaml
name: secure-app
service: secure-app
port: 8443
maxFails: 3
maxConns: 100
failTimeout: 30s
loadBalancingMethod: least_conn
```
| Поле | Описание | Тип | Обязательно |
|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `name` | Имя апстрима. Это должна быть допустимая метка DNS, как определено в RFC
1035. Например, допустимы значения `hello` и `upstream-123`. Имя
должно быть уникальным среди всех апстримов ресурса. | `string` | Да |
| `service` | Название [сервиса](https://kubernetes.io/docs/concepts/services-networking/service/).
Сервис должен принадлежать к тому же пространству имен, что и ресурс.
Если сервиса не существует, Angie предположит, что у него нет конечных
точек, и будет закрывать клиентские соединения и игнорировать
датаграммы. | `string` | Да |
| `port` | Порт службы. Если у сервиса этот порт не задан, Angie предположит, что у
него нет конечных точек, и будет закрывать клиентские соединения и
игнорировать датаграммы. Значение должно находиться в диапазоне
`1..65535`. | `int` | Да |
| `maxFails` | Задает [число](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) неудачных попыток установить связь с
сервером, которые должны произойти в течение времени, заданного
параметром `failTimeout`, чтобы сервер считался недоступным.
Значение по умолчанию: `1`. | `int` | Нет |
| `maxConns` | Задает максимальное число подключений к проксируемому
серверу. Значение по умолчанию равно нулю, что означает отсутствие
ограничений. Значение по умолчанию равно `0`. | `int` | Нет |
| `failTimeout` | Задает [время](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server), в течение которого должно произойти
указанное количество неудачных попыток установить связь с сервером, чтобы
считать сервер недоступным, и период времени, в течение которого сервер
будет считаться недоступным. Значение по умолчанию равно `10`
секундам. | `string` | Нет |
| `loadBalancingMethod` | Метод балансировки нагрузки между серверами апстрима. По умолчанию
соединения распределяются между серверами по методу взвешенной
циклической балансировки. Доступные методы и подробности смотрите в
разделе [Апстрим](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream). | `string` | Нет |
### UpstreamParameters
Различные параметры апстрима:
```yaml
upstreamParameters:
udpRequests: 1
udpResponses: 1
connectTimeout: 60s
nextUpstream: true
nextUpstreamTimeout: 50s
nextUpstreamTries: 1
```
| Поле | Описание | Тип | Обязательно |
|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `udpRequests` | Количество датаграмм, после получения которых следующая датаграмма от
того же клиента запускает новый сеанс. См. директиву
[proxy_requests](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-requests). Значение по умолчанию равно `0`. | `int` | Нет |
| `udpResponses` | Количество датаграмм, ожидаемых от проксируемого сервера в ответ на
клиентскую датаграмму. См. директиву [proxy_responses](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-responses). По
умолчанию количество датаграмм не ограничено. | `int` | Нет |
| `connectTimeout` | Тайм-аут установки соединения с проксируемым сервером. См. директиву
[proxy_connect_timeout](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-connect-timeout).
Значение по умолчанию - `60` секунд. | `string` | Нет |
| `nextUpstream` | Если соединение с проксируемым сервером установить не удается,
определяет, будет ли клиентское соединение передано на следующий сервер.
См. директиву [proxy_next_upstream](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-next-upstream).
Значение по умолчанию равно `true`. | `bool` | Нет |
| `nextUpstreamTries` | Количество попыток до передачи соединения к следующему серверу. См.
директиву [proxy_next_upstream_tries](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-next-upstream-tries).
Значение по умолчанию равно `0`. | `int` | Нет |
| `nextUpstreamTimeout` | Время, отведенное для передачи соединения к следующему серверу. См.
директиву [proxy_next_upstream_timeout](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-next-upstream-timeout).
Значение по умолчанию - `0`. | `string` | Нет |
### SessionParameters
Различные параметры для TCP-соединений и UDP-сеансов.
```yaml
sessionParameters:
timeout: 50s
```
| Поле | Описание | Тип | Обязательно |
|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `timeout` | Тайм-аут между двумя последовательными операциями чтения или записи в
соединениях с клиентом или проксируемым сервером. См. директиву
[proxy_timeout](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-timeout).
Значение по умолчанию равно `10m`. | `string` | Нет |
### Action
Действие, которое необходимо выполнить для клиентского соединения или
датаграммы.
В приведенном ниже примере клиентские подключения и датаграммы
передаются на апстрим в `dns-app`:
```yaml
action:
pass: dns-app
```
| Поле | Описание | Тип | Обязательно |
|--------|--------------------------------------------------------------------------------------------------------|----------|---------------|
| `pass` | Передает соединения и датаграммы апстриму. Апстрим
с таким именем должен быть определен в ресурсе. | `string` | Да |
## Использование TransportServer
Для работы с ресурсами TransportServer можно использовать обычные
команды `kubectl`, аналогично ресурсам Ingress.
Например, следующая команда создает ресурс TransportServer, определенный
в `transport-server-passthrough.yaml`, с именем `secure-app`:
```console
kubectl apply -f transport-server-passthrough.yaml
transportserver.k8s.angie.software/secure-app created
```
Вы можете получить ресурс, выполнив:
```console
kubectl get transportserver secure-app
NAME AGE
secure-app 46sm
```
В `kubectl get` и подобных командах также можно использовать короткое имя
`ts` вместо `transportserver`.
### Использование фрагментов
Фрагменты позволяют вставлять элементы конфигурации Angie в различные контексты
конфигурации Angie. В приведенном ниже примере мы используем фрагменты для
настройки [контроля доступа](https://angie.software//angie/docs/configuration/modules/stream/stream_access.md#stream-access) на TransportServer:
```yaml
apiVersion: k8s.angie.software/v1alpha1
kind: TransportServer
metadata:
name: cafe
spec:
host: cafe.example.com
serverSnippets: |
deny 192.168.1.1;
allow 192.168.1.0/24;
upstreams:
- name: tea
service: tea-svc
port: 80
```
Фрагменты также можно указать для потока. В приведенном ниже примере мы
используем фрагменты для [ограничения количества подключений](https://angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#stream-limit-conn):
```yaml
apiVersion: k8s.angie.software/v1alpha1
kind: TransportServer
metadata:
name: cafe
spec:
host: cafe.example.com
streamSnippets: limit_conn_zone $binary_remote_addr zone=addr:10m;
serverSnippets: limit_conn addr 1;
upstreams:
- name: tea
service: tea-svc
port: 80
```
Фрагменты предназначены для продвинутых пользователей Angie, которым
требуется больше контроля над генерируемой конфигурацией Angie.
Однако из-за недостатков, описанных ниже, фрагменты по умолчанию отключены.
Чтобы использовать фрагменты, задайте аргумент командной строки
`enable-snippets`.
Недостатки использования фрагментов:
- *Сложность*. Чтобы использовать фрагменты, требуется:
- Понимать примитивы конфигурации Angie и реализовать правильную
конфигурацию Angie.
- Понимать, как ANIC генерирует конфигурацию Angie, чтобы фрагмент не
мешал другим функциям конфигурации.
- *Сниженная надежность*. Неправильный фрагмент делает конфигурацию
Angie недействительной, что приведет к ошибке при перезагрузке. Это
помешает применить какие-либо обновления конфигурации, включая
обновления для другого ресурса TransportServer, пока фрагмент не
будет исправлен.
- *Последствия для безопасности*. Фрагменты предоставляют доступ к
примитивам конфигурации Angie, и эти примитивы не проверяются самим
ANIC.
#### NOTE
Пока конфигурация Angie содержит недопустимый фрагмент,
Angie будет продолжать работать с последней допустимой конфигурацией.
#### NOTE
Чтобы настроить фрагменты в контексте `stream`,
используйте ключ `stream-snippets` ConfigMap.
### Валидация
Для ресурса TransportServer доступны два типа валидации:
- *Структурная валидация* с помощью `kubectl` и сервера Kubernetes
API.
- *Всесторонняя валидация* с помощью ANIC.
#### Структурная валидация
Пользовательское определение ресурса для TransportServer включает
структурную схему OpenAPI, которая описывает тип каждого поля ресурса.
Если вы попытаетесь создать (или обновить) ресурс с нарушением
структурной схемы (например, используете строковое значение для поля
порта апстрима), сервер `kubectl` и Kubernetes API отклонят такой
ресурс:
- Пример проверки `kubectl`:
```console
kubectl apply -f transport-server-passthrough.yaml
error: error validating "transport-server-passthrough.yaml": error validating data: ValidationError(TransportServer.spec.upstreams[0].port): invalid type for software.angie.k8s.v1alpha1.TransportServer.spec.upstreams.port: got "string", expected "integer"; if you choose to ignore these errors, turn validation off with --validate=false
```
- Пример проверки сервера Kubernetes API:
```console
kubectl apply -f transport-server-passthrough.yaml --validate=false
The TransportServer "secure-app" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list:
spec.upstreams.port in body must be of type integer: "string"
```
Если ресурс не отклонен (то есть не нарушает структурную схему), ANIC
проверит его дополнительно.
#### Всесторонняя валидация
ANIC проверяет поля ресурса TransportServer. Если ресурс
недействителен, ANIC отклонит его: ресурс продолжит существовать
в кластере, но ANIC будет его игнорировать.
Вы можете проверить, успешно ли ANIC применил конфигурацию
TransportServer. Для примера TransportServer `secure-app` мы можем запустить:
```console
kubectl describe ts secure-app
. . .
Events:
Type Reason Age From Message
-----
Normal AddedOrUpdated 3s angie-ingress-controller Configuration for default/secure-app was added or updated
```
Обратите внимание, что раздел `Events` (События) включает событие `Normal` с
причиной `AddedOrUpdated`, которое информирует нас о том, что конфигурация была
успешно применена.
Если вы создадите недопустимый ресурс, ANIC отклонит его и выдаст
событие `Rejected`. Например, если вы создадите TransportServer `secure-app` с
действием `pass`, которое ссылается на несуществующий апстрим, вы получите:
```console
kubectl describe ts secure-app
. . .
Events:
Type Reason Age From Message
-----
Warning Rejected 2s angie-ingress-controller TransportServer default/secure-app is invalid and was rejected: spec.action.pass: Not found: "some-app"
```
Обратите внимание, что раздел событий включает событие `Warning` с причиной
`Rejected`.
#### NOTE
Если вы внесете ошибку в уже существующий ресурс, ANIC отклонит
его и удалит соответствующую конфигурацию из Angie.
### Настройка с помощью ConfigMap
Ключи `ConfigMap`
(за исключением `stream-snippets`, `stream-log-format`,
`resolver-addresses`, `resolver-ipv6`, `resolver-valid` и
`resolver-timeout`) не влияют на ресурсы TransportServer.
# https://angie.software/anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md
# VirtualServer, VirtualServerRoute
Ресурсы VirtualServer и VirtualServerRoute реализуют сценарии использования, не поддерживаемые
ресурсом Ingress, такие как разделение трафика и продвинутая маршрутизация на основе содержимого. Они
реализованы как [пользовательские ресурсы](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
.
Это справочная документация по обоим ресурсам.
## Спецификация VirtualServer
Ресурс VirtualServer определяет конфигурацию балансировки нагрузки для
доменного имени, например `example.com`. Ниже приведен пример такой
конфигурации:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: cafe
spec:
host: cafe.example.com
tls:
secret: cafe-secret
staticLocations:
- type: root
urlPath: /americano
dirPath: /latte
gunzip: on
upstreams:
- name: tea
service: tea-svc
port: 80
- name: coffee
service: coffee-svc
port: 80
routes:
authRequest: /auth/p
authRequestSets:
- key: foo
value: bar
matches:
- conditions:
- variable: $request_method
value: POST
action:
pass: tea-post
action:
pass: tea-post
- path: /coffee
action:
pass: coffee
- path: ~ ^/decaf/.\*\\.jpg$
action:
pass: coffee
- path: = /green/tea
action:
pass: tea
activeHealthProbes:
- name: activename1
upstream: tea
uri: uri
port: 80
interval: 3s
isEssential: true
isPersistent: true
maxBody: 10m
fails: 4
passes: 5
mode: onfail
maps:
- variable: $jwt_claim_iat
source: $oidc_client
parameters:
- value: 'myclient'
result: '80'
- variable: $jwt_claim_iss
source: $oidc_client
parameters:
- value: 'myclient'
result: 'PROVIDER_URL'
- variable: $jwt_claim_sub
source: $oidc_client
parameters:
- value: 'myclient'
result: 'myclient'
- variable: $jwt_claim_aud
source: $oidc_client
parameters:
- value: 'myclient'
result: 'myclient'
authRequestLocations:
- path: /auth/path
proxyPass:
upstreamName: "tea"
proxyPassHeaders:
- key: Content-Length
value: "100"
```
| Поле | Описание | Тип | Обязательно |
|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|---------------|
| `host` | Хост (доменное имя) сервера. Это должен быть допустимый поддомен, как
определено в RFC 1123, например `my-app` или `hello.example.com`.
При использовании домена с подстановочным знаком, например
`*.example.com`, домен должен быть заключен в двойные кавычки.
Значение `host` должно быть уникальным среди всех ресурсов Ingress и
VirtualServer. | `string` | Да |
| `tls` | Конфигурация терминации TLS. | [tls](#virtualservertls) | Нет |
| `staticLocations` | Список каталогов для раздачи статических файлов. | [staticLocations[ ]](#staticlocations) | Нет |
| `gunzip` | Включает или отключает [распаковку](https://angie.software//angie/docs/configuration/modules/http/http_gunzip.md#http-gunzip) архивированных
ответов для клиентов. Допустимые пары значений: "on" и "off", "true" и
"false" или "yes" и "no". Если значение `gunzip` не установлено, то по
умолчанию оно равно `off`. | `boolean` | Нет |
| `ExternalDNS` | Конфигурация ExternalDNS для VirtualServer. | [ExternalDNS](#virtualserverexternaldns) | Нет |
| `dos` | Ссылка на DosProtectedResource; установка этого параметра включает
защиту VirtualServer от DOS-атак. | `string` | Нет |
| `policies` | Список политик. | [policy[ ]](#virtualserverpolicy) | Нет |
| `upstreams` | Список апстримов. | [upstream[ ]](#virtualserverupstream) | Нет |
| `routes` | Список маршрутов. | [route[ ]](#virtualserverroute) | Нет |
| `activeHealthProbes` | Список активных проверок работоспособности. | [activeHealthProbes[ ]](#activehealthprobes) | Нет |
| `maps` | Список переменных, необходимых для валидации токенов в процессе [аутентификации OIDC](https://angie.software//anic/docs/configuration/policy-resource.md#oidc-policy). | [maps[ ]](#virtualserver-maps) | Нет |
| `ingressClassName` | Указывает, какой экземпляр ANIC должен обрабатывать ресурс
VirtualServer. | `string` | Нет |
| `internalRoute` | Указывает, является ли ресурс VirtualServer внутренним маршрутом. | `boolean` | Нет |
| `http-snippets` | Задает пользовательский фрагмент в контексте http. | `string` | Нет |
| `server-snippets` | Задает пользовательский фрагмент в контексте . Имеет приоритет над
ключом ConfigMap `server-snippets`. | `string` | Нет |
| `authRequestLocations` | Задает список точек авторизации клиента при настройке `authRequest`. | [authRequestLocations[ ]](#virtualserverroute-authrequestlocations) | Нет |
### VirtualServer.TLS
Поле tls определяет конфигурацию TLS для ресурса VirtualServer.
Например:
```yaml
secret: cafe-secret
redirect:
enable: true
ssl_session_timeout: 1h
ssl_session_cache: shared:SSL:10m
ssl_session_tickets: on
ssl_stapling: on
ssl_stapling_verify: on
```
| Поле | Описание | Тип | Обязательно |
|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------|
| `secret` | Имя секрета с сертификатом TLS и ключом. Секрет должен принадлежать тому
же пространству имен, что и VirtualServer. Секрет должен иметь тип
`kubernetes.io/tls` и содержать ключи с именами `tls.crt` и
`tls.key`, содержащие сертификат и закрытый ключ, как описано [здесь](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls).
Если секрет не существует или недействителен, Angie прервет любую
попытку установить TLS-соединение с хостом VirtualServer. Если секрет не
указан, но настроен секрет TLS с подстановочным знаком,
Angie будет использовать секрет со знаком для терминации TLS. | `string` | Нет |
| `redirect` | Конфигурация перенаправления TLS для VirtualServer. | [tls.redirect](#virtualservertlsredirect) | Нет |
| `cert-manager` | Конфигурация TLS cert-manager для VirtualServer. | [tls.cert-manager](#virtualservertlscertmanager) | Нет |
| `ssl_session_timeout` | Задает время, в течение которого клиент может повторно использовать параметры сессии. См. также директиву
[ssl_session_timeout](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-session-timeout) в документации Angie. Значение по умолчанию `10m`. | `string` | Нет |
| `ssl_session_cache` | Задает тип и размеры кэшей для хранения параметров сессий. См. также директиву
[ssl_session_cache](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-session-cache) в документации Angie. Значение по умолчанию `shared:SSL:10m`. | `string` | Нет |
| `sssl_session_tickets` | Разрешает или запрещает возобновление сессий при помощи TLS session tickets. См. также директиву
[ssl_session_tickets](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-session-tickets) в документации Angie. Значение по умолчанию `off`. | `string` | Нет |
| `ssl_stapling` | Разрешает или запрещает прикрепление OCSP-ответов сервером. См. также директиву
[ssl_stapling](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-stapling) в документации Angie. Значение по умолчанию `on`. | `string` | Нет |
| `ssl_stapling_verify` | Разрешает или запрещает проверку сервером ответов OCSP. См. также директиву
[ssl_stapling_verify](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-stapling-verify) в документации Angie. Значение по умолчанию `on`. | `string` | Нет |
### VirtualServer.TLS.Redirect
Поле перенаправления настраивает перенаправление TLS для VirtualServer:
```yaml
enable: true
code: 301
basedOn: scheme
```
| Поле | Описание | Тип | Обязательно |
|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------|
| `enable` | Включает перенаправление TLS для VirtualServer. Значение по умолчанию
равно `false`. | `boolean` | Нет |
| `код` | Код состояния перенаправления. Допустимые значения: `301`, `302`,
`307`, `308`. Значение по умолчанию - `301`. | `int` | Нет |
| `basedOn` | Атрибут запроса, который Angie будет оценивать для отправки
перенаправления. Допустимыми значениями являются `scheme` (схема
запроса) или `x-forwarded-proto` (заголовок `X-Forwarded-Proto`
запроса). Значение по умолчанию - `scheme`. | `string` | Нет |
### VirtualServer.TLS.CertManager
Поле cert-manager настраивает автоматическое управление сертификатами
x509 для ресурсов VirtualServer с помощью cert-manager
(cert-manager.io). Ознакомьтесь с [документацией по конфигурации
cert-manager](https://cert-manager.io/docs/configuration/) для
получения дополнительной информации о развертывании и настройке
эмитентов (Issuer). Пример:
```yaml
cert-manager:
cluster-issuer: "my-issuer-name"
```
| Поле | Описание | Тип | Обязательно |
|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `issuer` | Имя эмитента. Эмитент - это ресурс cert-manager, который описывает центр
сертификации, способный подписывать сертификаты. Он должен находиться в
том же пространстве имен, что и ресурс VirtualServer. Обратите внимание,
что требуется задать issuer или cluster-issuer, но эти параметры
взаимоисключающие - должен быть задан один и только один. | `string` | Нет |
| `cluster-issuer` | Имя ClusterIssuer. ClusterIssuer - это ресурс cert-manager, который
описывает центр сертификации, способный подписывать сертификаты. Не
имеет значения, в каком пространстве имен находится ваш VirtualServer,
поскольку ClusterIssuer - это ресурсы, не относящиеся к пространствам
имен. Обратите внимание, что требуется задать issuer или
cluster-issuer, но эти параметры взаимоисключающие - должен быть задан
один и только один. | `string` | Нет |
| `issuer-kind` | Тип внешнего ресурса-эмитента, например AWSPCAIssuer. Это необходимо
только для сторонних эмитентов. Его нельзя задавать, если также задан
cluster-issuer. | `string` | Нет |
| `issuer-group` | Группа API внешнего контроллера-эмитента, например
awspca.cert-manager.io. Это необходимо только для сторонних эмитентов.
Его нельзя задавать, если также задан cluster-issuer. | `string` | Нет |
| `common-name` | Это поле позволяет настроить spec.commonName для создаваемого
сертификата. Эта конфигурация добавляет CN к сертификату x509. | `string` | Нет |
| `duration` | Это поле позволяет настроить поле spec.duration для генерируемого
сертификата. Оно должно быть задано с использованием формата
[time.Duration](https://pkg.go.dev/time#ParseDuration) в Go, который
не допускает суффикса d (дни). Указывайте такие значения, используя
вместо них суффиксы s, m и h. | `string` | Нет |
| `renew-before` | Эта аннотация позволяет настроить поле spec.renewBefore для
генерируемого сертификата. Оно должно быть задано с использованием
формата [time.Duration](https://pkg.go.dev/time#ParseDuration) в Go,
который не допускает суффикса d (дни). Указывайте такие значения,
используя вместо них суффиксы s, m и h. | `string` | Нет |
| `usages` | Позволяет настроить поле spec.usages для генерируемого сертификата.
Задайте строку со значениями, разделенными запятыми, т. е. `соглашение
о ключе, цифровая подпись, серверная аутентификация`. Исчерпывающий
список поддерживаемых способов использования ключей можно найти в
[документации API cert-manager](https://cert-manager.io/docs/reference/api-docs/#cert-manager.io/v1.KeyUsage). | `string` | Нет |
### VirtualServer.ExternalDNS
Поле ExternalDNS настраивает динамическое управление записями DNS для
ресурсов VirtualServer с использованием
[ExternalDNS](https://github.com/kubernetes-sigs/external-dns) .
Ознакомьтесь [с документацией по конфигурации
ExternalDNS](https://kubernetes-sigs.github.io/external-dns/v0.12.0/)
для получения дополнительной информации о развертывании и настройке
ExternalDNS и поставщиков. Пример:
```yaml
enable: true
```
| Поле | Описание | Тип | Обязательно |
|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|---------------|
| `enable` | Включает интеграцию ExternalDNS для ресурса VirtualServer. Значение по
умолчанию равно `false`. | `string` | Нет |
| `labels` | Настраивает метки, применяемые к ресурсам конечной точки, которые будут
использоваться ExternalDNS. | `map[string]string` | Нет |
| `providerSpecific` | Настраивает свойства, относящиеся к конкретному поставщику, которые
содержат имя и значение конфигурации, специфичной для отдельных
поставщиков DNS. | [ProviderSpecific[ ]](#virtualserverexternaldnsproviderspecific) | Нет |
| `recordTTL` | TTL для записи DNS. По умолчанию это значение равно 0. См. [документацию
ExternalDNS TTL для определения значений по умолчанию для конкретного
поставщика](https://kubernetes-sigs.github.io/external-dns/v0.12.0/ttl/#providers) | `int64` | Нет |
| `recordType` | Тип создаваемой записи, например "A", "AAAA", "CNAME". Если значение не
задано, оно автоматически вычисляется на основе внешних конечных точек. | `string` | Нет |
### VirtualServer.ExternalDNS.ProviderSpecific
Поле providerSpecific блока ExternalDNS позволяет указать свойства,
специфичные для поставщика, которые представляют собой список пар
"ключ-значение" для конфигураций, специфичных для отдельных поставщиков
DNS. Пример:
```yaml
- name: my-name
value: my-value
- name: my-name2
value: my-value2
```
| Поле | Описание | Тип | Обязательно |
|---------|----------------------------------|----------|---------------|
| `name` | Имя в паре "ключ-значение". | `string` | Да |
| `value` | Значение в паре "ключ-значение". | `string` | Да |
### VirtualServer.Policy
Ссылается на [ресурс Policy](https://angie.software//anic/docs/configuration/policy-resource.md#policy-resource) по имени и
необязательному пространству имен. Например:
```yaml
name: access-control
```
| Поле | Описание | Тип | Обязательно |
|-------------|------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `name` | Имя политики. Если политика не существует или недействительна,
Angie выдаст сообщение об ошибке с кодом состояния `500`. | `string` | Да |
| `namespace` | Пространство имен политики. Если не указано, используется
пространство имен ресурса VirtualServer. | `string` | Нет |
### VirtualServer.Route
Маршрут определяет правила для сопоставления клиентских запросов с
такими действиями, как передача запроса апстриму. Например:
```yaml
path: /tea
action:
pass: tea
```
| Поле | Описание | Тип | Обязательно |
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|---------------|
| `path` | Путь маршрута. Angie сопоставит его с URI запроса. Возможные значения:
префикс (`/`, `/path`), точное совпадение (`=/exact/match`),
регулярное выражение без учета регистра (`~*^/Bar.*.jpg`) или
регулярное выражение с учетом регистра (`~^/foo.*.jpg`). В случае
префикса (должен начинаться с `/` ) или точного совпадения (должно
начинаться с `=` ) путь не должен содержать никаких пробельных
символов, `{` , `}` или `;`. В случае регулярных выражений все
двойные кавычки `"` должны быть экранированы, при этом совпадение не
может заканчиваться неэкранированной обратной косой чертой \\. Путь
должен быть уникальным среди путей всех маршрутов VirtualServer.
Дополнительные сведения см. в описании директивы
[location](https://angie.software//angie/docs/configuration/modules/http/index.md#location). | `string` | Да |
| `policies` | Список политик. Эти политики имеют приоритет над политиками того же
типа, определенными в `спецификации` VirtualServer. Более подробную
информацию смотрите в [Применение политик](https://angie.software//anic/docs/configuration/policy-resource.md#applying-policies). | [policy[ ]](#virtualserverpolicy) | Нет |
| `action` | Действие по умолчанию, выполняемое для запроса. | [Action](https://angie.software//anic/docs/configuration/transportserver-resource.md#action) | Нет |
| `dos` | Ссылка на DosProtectedResource; установка этого параметра включает
защиту маршрута VirtualServer от DOS-атак. | `string` | Нет |
| `splits` | Конфигурация разделения трафика по умолчанию. Должно быть не менее 2
разделений. | [Split](#split) | Нет |
| `matches` | Правила сопоставления для продвинутой маршрутизации на основе
содержимого. Требуется задать `action` или `splits` по умолчанию.
Несопоставленные запросы будут обрабатываться `action` или `splits`
по умолчанию. | [matches](#match) | Нет |
| `route` | Имя ресурса VirtualServerRoute, который определяет этот маршрут. Если
VirtualServerRoute не принадлежит к тому же пространству имен, что и
VirtualServer, необходимо включить пространство имен. Например:
`tea-namespace/tea`. | `string` | Нет |
| `errorPages` | Настраиваемые ответы на коды ошибок. Angie будет использовать эти ответы
вместо того, чтобы возвращать ответы об ошибках с серверов апстрима или
ответы по умолчанию, сгенерированные Angie. Настраиваемый ответ может
быть перенаправлением или сохраненным ответом. Например, это может быть
перенаправление на другой URL-адрес, если вышестоящий сервер ответил
кодом состояния 404. | [errorPage[ ]](#errorpage) | Нет |
| `location-snippets` | Задает пользовательский фрагмент в контексте местоположения. Имеет
приоритет над ключом ConfigMap `location-snippets`. | `string` | Нет |
| `authRequest` | Осуществляет авторизацию, основанную на результате выполнения подзапроса, и задает URI, на который будет отправлен подзапрос. | [auth_request[ ]](https://angie.software//angie/docs/configuration/modules/http/http_auth_request.md#id3) | Нет |
| `authRequestSets` | После завершения запроса авторизации устанавливает указанное значение для переменной в запросе. | [auth_request_set[ ]](https://angie.software//angie/docs/configuration/modules/http/http_auth_request.md#auth-request-set) | Нет |
#### NOTE
Маршрут должен включать в себя ровно одно из следующих действий:
`action`, `splits` или `route`.
### Maps
Определяет обязательные переменные `$jwt_claim_iat`, `$jwt_claim_iss`,
`$jwt_claim_sub` и `$jwt_claim_aud` для валидации токенов в процессе [аутентификации OIDC](https://angie.software//anic/docs/configuration/policy-resource.md#oidc-policy).
```yaml
- variable: $jwt_claim_iat
source: $oidc_client
parameters:
- value: 'myclient'
result: '80'
- variable: $jwt_claim_iss
source: $oidc_client
parameters:
- value: 'myclient'
result: 'PROVIDER_URL'
- variable: $jwt_claim_sub
source: $oidc_client
parameters:
- value: 'myclient'
result: 'myclient'
- variable: $jwt_claim_aud
source: $oidc_client
parameters:
- value: 'myclient'
result: 'myclient'
```
Пример включения переменных `map` в зависимости от входного значения (`default`, `volatile`, `include`, `hostnames`):
```yaml
maps:
- variable: $result_var
source: $host
parameters:
- value: 'default'
result: 'default_value'
- value: 'volatile'
result: ''
- value: 'include'
result: '/dev/stdout'
- value: 'example.com'
result: '1'
- value: '*.example.com'
result: '1'
```
См. также директиву [map](https://angie.software//angie/docs/configuration/modules/stream/stream_map.md#stream-map) в документации Angie.
| Поле | Описание | Тип | Обязательно |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `$jwt_claim_iat` | Настраивает параметр `iat` (issued at, время выпуска токена) для клиента. | `string` | Да |
| `$jwt_claim_iss` | Параметр `iss` (issuer, издатель токена) сопоставляется с URL-адресом `PROVIDER_URL`. Этот параметр указывает на сервис, выпустивший токен. | `string` | Да |
| `$jwt_claim_sub` | Параметр `sub` (subject, субъект токена). Идентифицирует пользователя или субъект, для которого был выдан токен. | `string` | Да |
| `$jwt_claim_aud` | Параметр `aud` (audience, аудитория). Идентифицирует клиент, для которого был предназначен токен. | `string` | Да |
### authRequestLocations
Задает список точек авторизации для настройки `authRequest`.
См. также директиву [auth_request](https://angie.software//angie/docs/configuration/modules/http/http_auth_request.md#id3) в документации Angie.
```yaml
authRequestLocations:
- path: /auth/path
proxyPass:
upstreamName: "tea"
proxyPassHeaders:
- key: Content-Length
value: "100"
```
| Поле | Описание | Тип | Обязательно |
|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `path` | Задает конкретный путь, на который будет отправляться запрос для проверки авторизации. | `string` | Да |
| `proxyPass` | Задает список апстримов, к которым будет направлен запрос. См. также директиву [proxy_pass](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-pass) в документации Angie. | `string` | Да |
| `proxyPassHeaders` | Список заголовков, которые будут добавлены или изменены при проксировании запросов. | `string` | Да |
## Спецификация VirtualServerRoute
Ресурс VirtualServerRoute определяет маршрут для VirtualServer. Он может
состоять из одного вложенного маршрута или нескольких. VirtualServerRoute
является альтернативой объединяемым типам Ingress.
В приведенном ниже примере виртуальный сервер `cafe` из пространства имен
`cafe-ns` определяет маршрут с путем `/coffee`, который далее определяется
через VirtualServerRoute `coffee` из пространства имен `coffee-ns`.
VirtualServer:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: cafe
namespace: cafe-ns
spec:
host: cafe.example.com
upstreams:
- name: tea
service: tea-svc
port: 80
routes:
- path: /tea
action:
pass: tea
- path: /coffee
route: coffee-ns/coffee
```
VirtualServerRoute:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServerRoute
metadata:
name: coffee
namespace: coffee-ns
spec:
host: cafe.example.com
upstreams:
- name: latte
service: latte-svc
port: 80
- name: espresso
service: espresso-svc
port: 80
subroutes:
- path: /coffee/latte
action:
pass: latte
- path: /coffee/espresso
action:
pass: espresso
```
Обратите внимание, что каждый вложенный маршрут должен иметь путь `path`,
начинающийся с того же префикса (здесь "/coffee"), что и в маршруте
VirtualServer. Кроме того, `host` в VirtualServerRoute должен совпадать с
`host` у VirtualServer.
| Поле | Описание | Тип | Обязательно |
|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|---------------|
| `host` | Хост (доменное имя) сервера. Это должен быть допустимый поддомен, как
определено в RFC 1123, например `my-app` или `hello.example.com`.
При использовании домена с подстановочным знаком, например
`*.example.com`, домен должен быть заключен в двойные кавычки.
Значение должно совпадать с `host` у VirtualServer, который ссылается
на этот ресурс. | `string` | Да |
| `upstreams` | Список апстримов. | [upstream[ ]](https://angie.software//anic/docs/configuration/transportserver-resource.md#upstream) | Нет |
| `subroutes` | Список вложенных маршрутов. | [subroute[ ]](#virtualserverroutesubroute) | Нет |
| `ingressClassName` | Указывает, какой экземпляр ANIC должен обрабатывать ресурс
VirtualServerRoute. Значение должно совпадать с `ingressClassName` у
VirtualServer, который ссылается на этот ресурс. | `string` | Нет |
### VirtualServerRoute.Subroute
Определяет правила сопоставления клиентских запросов и действий,
например передача запроса апстриму. Например:
```yaml
path: /coffee
action:
pass: coffee
```
| Поле | Описание | Тип | Обязательно |
|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|---------------|
| `path` | Путь вложенного маршрута. Angie сопоставит его с URI запроса. Возможные
значения: префикс (`/`, `/path`), точное совпадение
(`=/exact/match`), регулярное выражение без учета регистра
(`~*^/Bar.*.jpg`) или регулярное выражение с учетом регистра
(`~^/foo.*.jpg`). В случае префикса путь должен начинаться с того же
пути, что и путь маршрута VirtualServer, который ссылается на этот
ресурс. В случае точного совпадения или регулярного выражения путь
должен совпадать с путем маршрута VirtualServer, который ссылается на
этот ресурс. В случае префикса или точного совпадения путь не должен
содержать никаких пробельных символов, `{` , `}` или `;`. В
случае регулярных выражений все двойные кавычки `"` должны быть
экранированы, при этом совпадение не может заканчиваться
неэкранированной обратной косой чертой . Путь должен быть уникальным
среди путей всех вложенных маршрутов VirtualServerRoute. | `string` | Да |
| `policies` | Список политик. Эти политики имеют приоритет над *всеми* политиками,
определенными в маршруте VirtualServer, который ссылается на этот
ресурс. Они также имеют приоритет над политиками того же типа,
определенными в `спецификации` VirtualServer. Более подробную
информацию смотрите в разделе [Применение политик](https://angie.software//anic/docs/configuration/policy-resource.md#applying-policies). | [policy[ ]](#virtualserverpolicy) | Нет |
| `action` | Действие по умолчанию, выполняемое для запроса. | [Action](https://angie.software//anic/docs/configuration/transportserver-resource.md#action) | Нет |
| `dos` | Ссылка на DosProtectedResource; установка этого параметра включает
защиту вложенного маршрута VirtualServerRoute от DOS-атак. | `string` | Нет |
| `splits` | Конфигурация разделения трафика по умолчанию. Должно быть не менее 2
разделений. | [split[ ]](#split) | Нет |
| `matches` | Правила сопоставления для продвинутой маршрутизации на основе
содержимого. Требуется задать `action` или `splits` по умолчанию.
Несопоставленные запросы будут обрабатываться `action` или `splits`
по умолчанию. | [matches](#match) | Нет |
| `errorPages` | Настраиваемые ответы на коды ошибок. Angie будет использовать эти ответы
вместо того, чтобы возвращать ответы об ошибках с серверов апстрима или
ответы по умолчанию, сгенерированные Angie. Настраиваемый ответ может
быть перенаправлением или сохраненным ответом. Например, это может быть
перенаправление на другой URL-адрес, если вышестоящий сервер ответил
кодом состояния 404. | [errorPage[ ]](#errorpage) | Нет |
| `location-snippets` | Задает пользовательский фрагмент в контексте местоположения.
Переопределяет значение `location-snippets` VirtualServer (если
задано) или ключ ConfigMap `location-snippets`. | `string` | Нет |
#### NOTE
Вложенный маршрут должен включать в себя ровно одно из следующих действий:
`action` или `splits`.
## Общие части VirtualServer и VirtualServerRoute
### Upstream
Апстрим определяет конечное место назначения для конфигурации
маршрутизации. Например:
```yaml
name: tea
service: tea-svc
subselector:
version: canary
port: 80
lb-method: round_robin
fail-timeout: 10s
max-fails: 1
max-conns: 32
keepalive: 32
connect-timeout: 30s
read-timeout: 30s
send-timeout: 30s
next-upstream: "error timeout non_idempotent"
next-upstream-timeout: 5s
next-upstream-tries: 10
client-max-body-size: 2m
tls:
enable: true
```
#### NOTE
Протокол WebSocket поддерживается без какой-либо дополнительной настройки.
| Поле | Описание | Тип | Обязательно |
|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|---------------|
| `name` | Имя апстрима. Это должна быть допустимая метка DNS, как определено в RFC
1035. Например, допустимы значения `hello` и `upstream-123`. Имя
должно быть уникальным среди всех апстримов ресурса. | `string` | Да |
| `service` | Название [сервиса](https://kubernetes.io/docs/concepts/services-networking/service/).
Сервис должен принадлежать к тому же пространству имен, что и ресурс.
Если сервиса не существует, Angie предположит, что у него нет конечных
точек, и будет возвращать ответ `502` для запросов к этому апстриму. | `string` | Да |
| `subselector` | Выбирает поды внутри сервиса, используя ключи меток и значения. По
умолчанию выбраны все поды сервиса.
#### NOTE
Ожидается, что указанные метки будут присутствовать
в подах при их создании. Если метки подов
изменяются, ANIC не увидит это изменение до тех пор, пока
не будет изменено количество подов. | `map[string]string` | Нет |
| `use-cluster-ip` | Позволяет использовать IP-адрес кластера и порт сервиса вместо
использования IP-адреса и порта подов по умолчанию. Когда это поле
включено, поля, которые настраивают поведение Angie, относящееся к
нескольким серверам апстрима (например, `lb-method` и
`next-upstream`), не будут иметь никакого эффекта, поскольку ANIC
настроит Angie только с одним сервером апстрима, который
будет соответствовать IP-адресу кластера сервиса. | `boolean` | Нет |
| `port` | Порт службы. Если у сервиса не определен этот порт, Angie предположит,
что у него нет конечных точек, и будет возвращать ответ `502` для
запросов к этому апстриму. Значение должно находиться в диапазоне
`1..65535`. | `uint16` | Да |
| `lb-method` | Метод [балансировки нагрузки](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream). Чтобы использовать
циклический метод, укажите `round_robin`. Значение по умолчанию указано
в ключе `lb-method` ConfigMap. | `string` | Нет |
| `fail-timeout` | Время, в течение которого должно произойти указанное количество неудачных
попыток установить связь с сервером апстрима, чтобы он считался
недоступным. См. параметр `fail_timeout` директивы [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server).
Значение по умолчанию задано в ключе ConfigMap `fail-timeout`. | `string` | Нет |
| `max-fails` | Количество неудачных попыток установить связь с сервером апстрима,
которые должны произойти в течение времени, заданного в
`fail-timeout`, чтобы считать сервер недоступным. См. параметр
[max_fails](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails)
директивы сервера. Значение по умолчанию задано в ключе ConfigMap
`max-fails`. | `int` | Нет |
| `max-conns` | Максимальное количество одновременных активных подключений к серверу
апстрима. См. параметр `max_conns`
директивы [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server). По умолчанию ограничений нет.
#### NOTE
Если включены соединения keepalive, общее
количество активных и неактивных соединений keepalive
к серверу апстрима может превышать значение `max_conns`. | `int` | Нет |
| `keepalive` | Настраивает кэш для подключений к серверам апстрима. Значение `0`
отключает кэш. См. директиву [keepalive](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive). Значение
по умолчанию задано в ключе ConfigMap `keepalive`. | `int` | Нет |
| `connect-timeout` | Тайм-аут для установления соединения с сервером апстрима. См. директиву
[proxy_connect_timeout](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-connect-timeout).
Значение по умолчанию указано в ключе ConfigMap `proxy-connect-timeout`. | `string` | Нет |
| `read-timeout` | Тайм-аут для чтения ответа от сервера апстрима. См. директиву
[proxy_read_timeout](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-read-timeout).
Значение по умолчанию указано в ключе ConfigMap `proxy-read-timeout`. | `string` | Нет |
| `send-timeout` | Тайм-аут для передачи запроса на сервер апстрима. См. директиву
[proxy_send_timeout](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-send-timeout).
Значение по умолчанию указано в ключе ConfigMap `proxy-send-timeout`. | `string` | Нет |
| `next-upstream` | Указывает, в каких случаях запрос должен быть передан следующему серверу
апстрима. См. директиву [proxy_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream).
Значение по умолчанию - `тайм-аут ошибки`. | `string` | Нет |
| `next-upstream-timeout` | Время, в течение которого запрос может быть передан следующему серверу
апстрима. См. директиву [proxy_next_upstream_timeout](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream-timeout).
Значение `0` отключает ограничение по времени. Значение по умолчанию
равно `0`. | `string` | Нет |
| `next-upstream-tries` | Количество возможных попыток передачи запроса на следующий сервер
апстрима. См. директиву [proxy_next_upstream_tries](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream-tries).
Значение `0` отключает это ограничение. Значение по умолчанию равно
`0`. | `int` | Нет |
| `client-max-body-size` | Задает максимальный размер текста клиентского запроса. См. директиву
[client_max_body_size](https://angie.software//angie/docs/configuration/modules/http/index.md#client-max-body-size).
Значение по умолчанию задано в ключе ConfigMap `client-max-body-size`. | `string` | Нет |
| `tls` | Конфигурация TLS для апстрима. | [tls](#upstreamtls) | Нет |
| `buffering` | Включает буферизацию ответов от сервера апстрима. См. директиву
[proxy_buffering](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-buffering).
Значение по умолчанию задано в ключе ConfigMap `proxy-buffering`. | `boolean` | Нет |
| `buffers` | Настраивает буферы, используемые для чтения ответа от сервера апстрима в
рамках одного соединения. | [buffers](#upstreambuffers) | Нет |
| `buffer-size` | Устанавливает размер буфера, используемого для считывания первой части
ответа, полученного от сервера апстрима. См. директиву
[proxy_buffer_size](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-buffer-size).
Значение по умолчанию задано в ключе ConfigMap `proxy-buffer-size`. | `string` | Нет |
| `type` | Тип апстрима. Поддерживаются значения `http` и `grpc`. По умолчанию
используется `http`. Для gRPC необходимо включить HTTP/2 в
`ConfigMap` и настроить терминацию TLS на VirtualServer. | `string` | Нет |
### Upstream.Buffers
Настраивает буферы, используемые для чтения ответа от сервера апстрима в
рамках одного соединения.
```yaml
number: 4
size: 8K
```
См. директиву
[proxy_buffers](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-buffers)
для получения дополнительной информации.
| Поле | Описание | Тип | Обязательно |
|----------|----------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `number` | Задает количество буферов. Значение по умолчанию задано в ключе ConfigMap `proxy-buffers`. | `int` | Да |
| `size` | Задает размер буфера. Если значение не указано, то по умолчанию будет задано 8K. См. также ключ ConfigMap `proxy-buffers`. | `string` | Нет |
### Upstream.TLS
| Поле | Описание | Тип | Обязательно |
|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------|
| `enable` | Включает HTTPS для запросов к серверам апстрима. Значение по умолчанию
равно `False`, что означает, что будет использоваться HTTP.
#### NOTE
По умолчанию Angie не будет проверять сертификат вышестоящего сервера.
Чтобы включить проверку, настройте [политику EgressMTLS](https://angie.software//anic/docs/configuration/policy-resource.md#egressmtls). | `boolean` | Нет |
### Upstream.SessionCookie
Поле SessionCookie настраивает сохранение сеансов, что позволяет
передавать запросы от одного и того же клиента на один и тот же сервер
апстрима. Информация о назначенном сервере апстрима передается в
сеансовом cookie, сгенерированном Angie.
В приведенном ниже примере мы настраиваем сохранение сеанса с помощью
cookie сеанса для апстрима и задаем все доступные параметры:
```yaml
name: tea
service: tea-svc
port: 80
sessionCookie:
enable: true
name: srv_id
path: /
expires: 1h
domain: .example.com
httpOnly: false
secure: true
samesite: strict
```
См. директиву [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) для получения дополнительной информации. Сеансовый
cookie соответствует методу `sticky cookie`.
| Поле | Описание | Тип | Обязательно |
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------|
| `enable` | Включает сохранение сеанса с помощью сеансового cookie для сервера
апстрима. Значение по умолчанию равно `false`. | `boolean` | Нет |
| `name` | Имя cookie. | `string` | Да |
| `path` | Путь, для которого установлен cookie. | `string` | Нет |
| `expires` | Время, в течение которого браузер должен сохранять cookie. Может быть
установлено специальное значение `max`; тогда срок действия cookie
истечет `31 декабря 2037 года в 23:55:55 по Гринвичу`. | `string` | Нет |
| `domain` | Домен, для которого установлен cookie. | `string` | Нет |
| `httpOnly` | Добавляет атрибут `HttpOnly` к cookie. | `boolean` | Нет |
| `secure` | Добавляет атрибут `Secure` к cookie. | `boolean` | Нет |
| `samesite` | Добавляет атрибут `SameSite` к cookie. Допустимые значения:
`strict`, `lax`, `none` | `string` | Нет |
### Upstream.SessionRoute
Поле sessionRoute настраивает сохранение маршрутов, что позволяет
передавать запросы от одного и того же клиента на один и тот же сервер
апстрима. Информация о назначенном сервере апстрима поддерживается в режиме
`route ` в Angie.
В приведенном ниже примере мы формируем директиву Angie
`sticky route $cookie_route $arg_route;`:
```yaml
sessionRoute:
enable: true
variables:
\- "\$cookie_route"
\- "\$arg_route"
```
См. описание режима `route` директивы [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) для получения
дополнительной информации.
Параметры:
| Поле | Описание | Тип | Обязательно |
|-------------|------------------------------------------------------------------------------------------------------------|-------------|---------------|
| `enable` | Включает сохранение сеанса в режиме `route` для сервера
апстрима. Значение по умолчанию равно `false`. | `boolean` | Нет |
| `variables` | Список переменных, подставляемых в директиву `sticky route`
в порядке следования. | `string[ ]` | Нет |
### ActiveHealthProbes
Поле позволяет настроить активную проверку работоспособности (health probe)
для [upstream](#virtualserverupstream). Вам необходимо задать
имя проверки `name` и `upstream`, к которому она относится, а также другие параметры.
Подробное описание параметров для активной проверки работоспособности см. в документации Angie,
директива [upstream_probe](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#http-upstream-probe).
Пример:
```yaml
activeHealthProbes:
- name: activename1
upstream: tea-post
uri: uri
port: 80
interval: 3s
isEssential: true
isPersistent: true
maxBody: 10m
fails: 4
passes: 5
mode: onfail
```
### staticLocations
Поле позволяет задать каталог, из которого будут раздаваться статические файлы.
Вы можете указать корневой каталог с помощью директивы
[root](https://angie.software//angie/docs/configuration/modules/http/index.md#root)
или другое расположение с помощью директивы
[alias](https://angie.software//angie/docs/configuration/modules/http/index.md#alias),
см. описания директив в документации Angie.
Пример конфигурации:
```yaml
staticLocations:
- type: root
urlPath: /static
dirPath: /var/www/html
```
| Поле | Описание | Тип | Обязательно |
|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `type` | Способ определения пути к каталогу, из которого будут раздаваться статические файлы.
Возможные значения: `root`, `alias`. | `string` | Да |
| `urlPath` | Префикс URL-адресов запрашиваемых статических файлов, используемый для
[location](https://angie.software//angie/docs/configuration/modules/http/index.md#location);
см. описание директивы в документации Angie. | `string` | Да |
| `dirPath` | Каталог файловой системы, из которого будут обслуживаться запросы к указанному URL-адресу. | `string` | Да |
### Header
Определяет HTTP-заголовок:
```yaml
name: Host
value: example.com
```
| Поле | Описание | Тип | Обязательно |
|---------|---------------------|----------|---------------|
| `name` | Имя заголовка. | `string` | Да |
| `value` | Значение заголовка. | `string` | Нет |
### Action
Определяет действие, которое необходимо выполнить для запроса.
В приведенном ниже примере клиентские запросы передаются на апстрим
`coffee`:
```yaml
path: /coffee
action:
pass: coffee
```
| Поле | Описание | Тип | Обязательно |
|------------|-----------------------------------------------------------------------------------------------------------------------------------|------------------------------------|---------------|
| `pass` | Передает запросы серверу апстрима. Апстрим с таким именем должен быть
определен в ресурсе. | `string` | Нет |
| `redirect` | Перенаправляет запросы на указанный URL-адрес. | [action.redirect](#actionredirect) | Нет |
| `return` | Возвращает предварительно сконфигурированный ответ. | [action.return](#actionreturn) | Нет |
| `proxy` | Передает запросы апстриму, добавляет возможность изменять запрос и ответ
(например, переписывать URI или изменять заголовки). | [action.proxy](#actionproxy) | Нет |
#### NOTE
Действие должно включать в себя ровно одно из следующих значений: `pass`,
`redirect`, `return` или `proxy`.
### Action.Redirect
Определяет перенаправление, возвращаемое для запроса.
В приведенном ниже примере клиентские запросы направляются на URL-адреса
`http://myhost.ru`:
```yaml
redirect:
url: http://myhost.ru
code: 301
```
| Поле | Описание | Тип | Обязательно |
|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `url` | URL-адрес, на который будет перенаправлен запрос. Поддерживаемые переменные Angie:
`$scheme` , `$http_x_forwarded_proto` , `$request_uri` , `$host`.
Переменные должны быть заключены в фигурные скобки. Например:
`$*host*$*request_uri*`. | `string` | Да |
| `код` | Код состояния перенаправления. Допустимые значения: `301`, `302`, `307`, `308`.
Значение по умолчанию - `301`. | `int` | Нет |
### Action.Return
Определяет предварительно сконфигурированный ответ на запрос.
В приведенном ниже примере Angie будет отвечать предварительно
настроенным ответом на каждый запрос:
```yaml
return:
code: 200
type: text/plain
body: "Hello World\n"
```
| Поле | Описание | Тип | Обязательно |
|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `код` | Код состояния ответа. Допустимые значения: `2XX`, `4XX` или `5XX`.
Значение по умолчанию равно `200`. | `int` | Нет |
| `тип` | MIME-тип ответа. Значение по умолчанию - `text/plain`. | `string` | Нет |
| `body` | Основная часть ответа. Поддерживает переменные Angie\*. Переменные должны
быть заключены в фигурные скобки. Например: `Запрос равен $*request_uri*n`. | `string` | Да |
#### NOTE
Поддерживаемые переменные Angie: `$request_uri`, `$request_method`,
`$request_body`, `$scheme`, `$http_`, `$args`, `$arg_`,
`$cookie_`, `$host`, `$request_time`, `$request_length`,
`$angie_version`, `$pid`, `$connection`, `$remote_addr`,
`$remote_port`, `$time_iso8601`, `$time_local`, `$server_addr`,
`$server_port`, `$server_name`, `$server_protocol`,
`$connections_active`, `$connections_reading`, `$connections_writing`
и `$connections_waiting`.
### Action.Proxy
Передает запросы апстриму с возможностью изменять запрос и ответ
(например, переписывать URI или изменять заголовки).
В приведенном ниже примере URI запроса переписывается на `/`, а
заголовки запроса и ответа изменяются:
```yaml
proxy:
upstream: coffee
requestHeaders:
pass: true
set:
- name: My-Header
value: Value
- name: Client-Cert
value: ${ssl_client_escaped_cert}
responseHeaders:
add:
- name: My-Header
value: Value
- name: IC-Angie-Version
value: ${angie_version}
always: true
hide:
- x-internal-version
ignore:
- Expires
- Set-Cookie
pass:
- Server
rewritePath: /
```
| Поле | Описание | Тип | Обязательно |
|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------|---------------|
| `upstream` | Имя апстрима, куда будут проксироваться запросы. Апстрим с таким именем
должен быть определен в ресурсе. | `string` | Да |
| `requestHeaders` | Изменения заголовков запросов. | [Action.Proxy.RequestHeaders](#actionproxyrequestheaders) | Нет |
| `responseHeaders` | Изменения в заголовках ответов. | [Action.Proxy.ResponseHeaders](#actionproxyresponseheaders) | Нет |
| `rewritePath` | Переписанный URI. Если путь маршрута является регулярным выражением, т.
е. начинается с ~, то rewritePath может включать группы захвата
`$1-9`. Например, $1 - первая группа, и так далее. | `string` | Нет |
### Action.Proxy.RequestHeaders
Поле requestHeaders изменяет заголовки запроса к проксируемому серверу
апстрима.
| Поле | Описание | Тип | Обязательно |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------|
| `pass` | Передает исходные заголовки запроса на проксируемый сервер апстрима.
Дополнительные сведения см. в описании директивы
[proxy_pass_request_headers](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass-request-headers).
Значение по умолчанию - true. | `bool` | Нет |
| `set` | Позволяет переопределять или добавлять поля для представления заголовков
запросов, передаваемых на проксируемые серверы апстрима. Дополнительные
сведения см. в описании директивы [proxy_set_header](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-set-header). | [header[ ]](#actionproxyrequestheaderssetheader) | Нет |
### Action.Proxy.RequestHeaders.Set.Header
Определяет HTTP-заголовок:
```yaml
name: My-Header
value: My-Value
```
Можно переопределить значение заголовка `Host` по умолчанию, которое ANIC
устанавливает равным [$host](https://angie.software//angie/docs/configuration/modules/http/index.md#v-host):
```yaml
name: Host
value: example.com
```
| Поле | Описание | Тип | Обязательно |
|---------|-------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `name` | Имя заголовка. | `string` | Да |
| `value` | Значение заголовка. Поддерживает переменные Angie\*. Переменные должны
быть заключены в фигурные скобки. Например: `$*scheme*`. | `string` | Нет |
#### NOTE
Поддерживаемые переменные Angie: `$request_uri`, `$request_method`,
`$request_body`, `$scheme`, `$http_`, `$args`, `$arg_`,
`$cookie_`, `$host`, `$request_time`, `$request_length`,
`$angie_version`, `$pid`, `$connection`, `$remote_addr`,
`$remote_port`, `$time_iso8601`, `$time_local`, `$server_addr`,
`$server_port`, `$server_name`, `$server_protocol`,
`$connections_active`, `$connections_reading`, `$connections_writing`,
`$connections_waiting`, `$ssl_cipher`, `$ssl_ciphers`,
`$ssl_client_cert`, `$ssl_client_escaped_cert`,
`$ssl_client_fingerprint`, `$ssl_client_i_dn`,
`$ssl_client_i_dn_legacy`, `$ssl_client_raw_cert`, `$ssl_client_s_dn`,
`$ssl_client_s_dn_legacy`, `$ssl_client_serial`, `$ssl_client_v_end`,
`$ssl_client_v_remain`, `$ssl_client_v_start`, `$ssl_client_verify`,
`$ssl_curves`, `$ssl_early_data`, `$ssl_protocol`,
`$ssl_server_name`, `$ssl_session_id`, `$ssl_session_reused`.
### Action.Proxy.ResponseHeaders
Поле responseHeaders изменяет заголовки ответа клиенту.
| Поле | Описание | Тип | Обязательно |
|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|---------------|
| `hide` | Заголовки, которые не будут переданы в ответе клиенту с проксируемого
сервера апстрима. Дополнительные сведения см. в описании директивы
[proxy_hide_header](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-hide-header). | `string[ ]` | Нет |
| `pass` | Позволяет передавать скрытые поля заголовка клиенту с проксируемого
сервера апстрима. Дополнительные сведения см. в описании директивы
[proxy_pass_header](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass-header). | `string[ ]` | Нет |
| `ignore` | Отключает обработку определенных заголовков\*\* при передаче клиенту
ответа с проксируемого сервера апстрима. Дополнительные сведения см. в
описании директивы [proxy_ignore_headers](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ignore-headers). | `string[ ]` | Нет |
| `add` | Добавляет заголовки к ответу для клиента. | [addHeader[ ]](#addheader) | Нет |
#### NOTE
Скрытые заголовки по умолчанию: `Date`, `Server`, `X-Pad` и
`X-Accel-...`.
#### NOTE
Следующие поля могут быть проигнорированы: `X-Accel-Redirect`,
`X-Accel-Expires`, `X-Accel-Limit-Rate`, `X-Accel-Buffering`,
`X-Accel-Charset`, `Expires`, `Cache-Control`, `Set-Cookie` и
`Vary`.
### AddHeader
Определяет HTTP-заголовок с необязательным полем `always`:
```yaml
name: My-Header
value: My-Value
always: true
```
| Поле | Описание | Тип | Обязательно |
|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `name` | Имя заголовка. | `string` | Да |
| `value` | Значение заголовка. Поддерживает переменные Angie\*. Переменные должны
быть заключены в фигурные скобки. Например: `$*scheme*`. | `string` | Нет |
| `always` | Если установлено значение true, добавляет заголовок независимо от кода
состояния ответа\*\*. Значение по умолчанию - false. Дополнительные
сведения см. в описании директивы [add_header](https://angie.software//angie/docs/configuration/modules/http/http_headers.md#add-header). | `bool` | Нет |
#### NOTE
Поддерживаемые переменные Angie: `$request_uri`, `$request_method`,
`$request_body`, `$scheme`, `$http_`, `$args`, `$arg_`,
`$cookie_`, `$host`, `$request_time`, `$request_length`,
`$angie_version`, `$pid`, `$connection`, `$remote_addr`,
`$remote_port`, `$time_iso8601`, `$time_local`, `$server_addr`,
`$server_port`, `$server_name`, `$server_protocol`,
`$connections_active`, `$connections_reading`, `$connections_writing`,
`$connections_waiting`, `$ssl_cipher`, `$ssl_ciphers`,
`$ssl_client_cert`, `$ssl_client_escaped_cert`,
`$ssl_client_fingerprint`, `$ssl_client_i_dn`,
`$ssl_client_i_dn_legacy`, `$ssl_client_raw_cert`, `$ssl_client_s_dn`,
`$ssl_client_s_dn_legacy`, `$ssl_client_serial`, `$ssl_client_v_end`,
`$ssl_client_v_remain`, `$ssl_client_v_start`, `$ssl_client_verify`,
`$ssl_curves`, `$ssl_early_data`, `$ssl_protocol`,
`$ssl_server_name`, `$ssl_session_id`, `$ssl_session_reused`.
#### NOTE
Если значение `always` - false, заголовок ответа добавляется только в том
случае, если код состояния ответа - это `200`, `201`, `204`, `206`,
`301`, `302`, `303`, `304`, `307` или `308`.
### Split
Определяет вес действия в составе конфигурации разделений.
В приведенном ниже примере Angie передает 80% запросов вышестоящему
`coffee-v1`, а оставшиеся 20% - `coffee-v2`:
```yaml
splits:
- weight: 80
action:
pass: coffee-v1
- weight: 20
action:
pass: coffee-v2
```
| Поле | Описание | Тип | Обязательно |
|----------|---------------------------------------------------------------------------------------------------------------------|-----------------|---------------|
| `weight` | Вес действия. Значение должно попадать в диапазон `1..99`. Сумма весов
всех разделений должна быть равна `100`. | `int` | Да |
| `action` | Действие, которое необходимо выполнить для запроса. | :ref\`:action\` | Да |
### Match
Определяет сопоставление между условиями и действием или разделениями.
В приведенном ниже примере Angie направляет запросы с путем "/coffee" в
разные апстримы на основе значения cookie `user`:
- `user=john` -> `coffee-future`
- `user=bob` -> `coffee-deprecated`
- Если cookie не установлен или не равен ни `john`, ни `bob`, Angie
перенаправляет запрос в `coffee-stable`
```yaml
path: /coffee
matches:
- conditions:
- cookie: user
value: john
action:
pass: coffee-future
- conditions:
- cookie: user
value: bob
action:
pass: coffee-deprecated
action:
pass: coffee-stable
```
В следующем примере Angie направляет запросы на основе значения встроенной
переменной [$request_method](https://angie.software//angie/docs/configuration/modules/http/index.md#v-request-method), которая представляет HTTP-метод запроса:
- все запросы POST -> `coffee-post`
- все прочие запросы -> `coffee`
```yaml
path: /coffee
matches:
- conditions:
- variable: $request\_method
value: POST
action:
pass: coffee-post
action:
pass: coffee
```
| Поле | Описание | Тип | Обязательно |
|--------------|--------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|---------------|
| `conditions` | Список условий. Должен включать по крайней мере одно условие. | [condition[ ]](#condition) | Да |
| `action` | Действие, которое необходимо выполнить для запроса. | [Action](https://angie.software//anic/docs/configuration/transportserver-resource.md#action) | Нет |
| `splits` | Конфигурация разбиений для разделения трафика. Должно быть указано не
менее двух разделений. | [split[ ]](#split) | Нет |
#### NOTE
Сопоставление должно использовать ровно одно из следующих значений:
`action` или `splits`.
### Condition
Определяет условие в сопоставлении.
| Поле | Описание | Тип | Обязательно |
|------------|----------------------------------------------------------------------------------------------------------|----------|---------------|
| `header` | Имя заголовка. Должно состоять из буквенно-цифровых символов или `-`. | `string` | Нет |
| `cookie` | Имя cookie. Должно состоять из буквенно-цифровых символов или `_`. | `string` | Нет |
| `argument` | Имя аргумента. Должно состоять из буквенно-цифровых символов или `_`. | `string` | Нет |
| `variable` | Имя переменной Angie. Должно начинаться с `$`. См. список
поддерживаемых переменных после таблицы. | `string` | Нет |
| `value` | Значение, которому должно соответствовать условие. Как определить
значение, показано ниже в таблице. | `string` | Да |
#### NOTE
Условие должно включать ровно одно из следующих значений: `header`,
`cookie`, `argument` или `variable`.
Поддерживаемые переменные Angie: `$args`, `$http2`, `$https`,
`$remote_addr`, `$remote_port`, `$query_string`, `$request`,
`$request_body`, `$request_uri`, `$request_method`, `$scheme`.
Значение поддерживает два вида сопоставления:
- *Сравнение строк без учета регистра*. Например:
- `john` - сопоставление без учета регистра, которое выполняется
успешно для таких строк, как `john`, `John`, `JOHN`.
- `!john` - отрицание соответствия без учета регистра для john,
которое выполняется успешно для таких строк, как `bob`,
`anything`, `"` (пустая строка).
- *Сопоставление с регулярным выражением*. Обратите внимание, что Angie
поддерживает регулярные выражения, совместимые с языком
программирования Perl (PCRE). Например:
- `~^yes` - регулярное выражение с учетом регистра, которое
соответствует любой строке, начинающейся с `yes`. Например:
`yes`, `yes123`.
- `!~^yes` - отрицание предыдущего регулярного выражения, которое
успешно выполняется для строк типа `YES`, `Yes123`, `noyes`.
(Механизм отрицания не является частью синтаксиса PCRE).
- `~*no$` -- регулярное выражение без учета регистра, которое
соответствует любой строке, заканчивающейся на `no`. Например:
`no`, `123no`, `123NO`.
#### NOTE
Значение не должно содержать неэкранированных двойных кавычек (`"`) и не
должно заканчиваться неэкранированной обратной косой чертой (`\`).
Например, следующие значения недопустимы: `some"value`, `somevalue\`.
### ErrorPage
Определяет настраиваемый ответ для маршрута на случай, когда сервер апстрима
отвечает кодом состояния ошибки (или его генерирует Angie). В качестве ответа
может быть задано перенаправление или сохраненный ответ. Дополнительные
сведения см. в описании директивы [error_page](https://angie.software//angie/docs/configuration/modules/http/index.md#error-page).
```yaml
path: /coffee
errorPages:
- codes: [502, 503]
redirect:
code: 301
url: https://angie.software
- codes: [404]
return:
code: 200
body: "Original resource not found, but success!"
```
| Поле | Описание | Тип | Обязательно |
|------------|-------------------------------------------------------------|------------------------------------------|---------------|
| `codes` | Список кодов состояния ошибки. | `int[ ]` | Да |
| `redirect` | Действие перенаправления для заданных кодов состояния. | [errorPage.Redirect](#errorpageredirect) | Нет |
| `return` | Сохраненное ответное действие для заданных кодов состояния. | [errorPage.Return](#errorpagereturn) | Нет |
#### NOTE
Страница с ошибкой должна содержать ровно одно из следующих значений:
`return` или `redirect`.
### ErrorPage.Redirect
Определяет перенаправление для errorPage.
В приведенном ниже примере Angie отвечает перенаправлением, когда ответ
от сервера апстрима имеет код состояния 404.
```yaml
codes: [404]
redirect:
code: 301
url: ${scheme}://cafe.example.com/error.html
```
| Поле | Описание | Тип | Обязательно |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `код` | Код состояния перенаправления. Допустимые значения: `301`,
`302`, `307`, `308`. Значение по умолчанию - `301`. | `int` | Нет |
| `url` | URL-адрес, на который будет перенаправлен запрос.
Поддерживаемые переменные Angie: `$scheme` и `$http_x_forwarded_proto`.
Переменные должны быть заключены в фигурные скобки. Например: `$*scheme*`. | `string` | Да |
### ErrorPage.Return
Определяет сохраненный ответ для errorPage.
В приведенном ниже примере Angie выдает сохраненный ответ, когда ответ
от сервера апстрима имеет код состояния 401 или 403.
```yaml
codes: [401, 403]
return:
code: 200
type: application/json
body: |
{\"msg\": \"You don't have permission to do this\"}
headers:
- name: x-debug-original-statuses
value: ${upstream\_status}
```
| Поле | Описание | Тип | Обязательно |
|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|---------------|
| `code` | Код состояния ответа. По умолчанию используется код состояния исходного
ответа. | `int` | Нет |
| `type` | MIME-тип ответа. Значение по умолчанию - `text/html`. | `string` | Нет |
| `body` | Тело ответа. Поддерживаемая переменная Angie: `$upstream_status`.
Переменные должны быть заключены в фигурные скобки. Например:
`$*upstream_status*`. | `string` | Да |
| `headers` | Настраиваемые заголовки ответа. | [errorPage.Return.Header](#errorpagereturnheader) | Нет |
### ErrorPage.Return.Header
Определяет HTTP-заголовок для сохраненного ответа у errorPage:
```yaml
name: x-debug-original-statuses
value: ${upstream_status}
```
| Поле | Описание | Тип | Обязательно |
|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------------|
| `name` | Имя заголовка. | `string` | Да |
| `value` | Значение заголовка. Поддерживаемая переменная
Angie: `$upstream_status`. Переменные должны быть
заключены в фигурные скобки. Например: `$*upstream_status*`. | `string` | Нет |
## Использование VirtualServer и VirtualServerRoute
Для работы с ресурсами VirtualServer и VirtualServerRoute можно
использовать обычные команды `kubectl`, аналогично ресурсам Ingress.
Например, следующая команда создает ресурс VirtualServer, определенный в
`cafe-virtual-server.yaml` с именем `cafe`:
```console
kubectl apply -f cafe-virtual-server.yaml
virtualserver.k8s.angie.software "cafe" created
```
Вы можете получить ресурс, выполнив:
```console
kubectl get virtualserver cafe
NAME STATE HOST IP PORTS AGE
cafe Valid cafe.example.com 12.13.23.123 [80,443] 3m
```
В `kubectl get` и подобных командах также можно использовать короткое
имя `vs` вместо `virtualserver`.
Работать с ресурсами VirtualServerRoute можно аналогично. В командах
kubectl используйте `virtualserverroute` или короткое имя `vsr`.
### Использование фрагментов
Фрагменты позволяют вставлять элементы конфигурации Angie в различные
контексты конфигурации Angie. В приведенном ниже примере мы используем
фрагменты кода для настройки нескольких функций Angie на VirtualServer:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: cafe
namespace: cafe
spec:
http-snippets: |
limit_req_zone $binary_remote_addr zone=mylimit:10m rate=1r/s;
proxy_cache_path /tmp keys_zone=one:10m;
host: cafe.example.com
tls:
secret: cafe-secret
server-snippets: |
limit_req zone=mylimit burst=20;
upstreams:
- name: tea
service: tea-svc
port: 80
- name: coffee
service: coffee-svc
port: 80
routes:
- path: /tea
location-snippets: |
proxy\_cache one;
proxy\_cache\_valid 200 10m;
action:
pass: tea
- path: /coffee
action:
pass: coffee
```
Фрагменты предназначены для продвинутых пользователей Angie, которым требуется
больше контроля над генерируемой конфигурацией Angie.
Однако из-за недостатков, описанных ниже, фрагменты по умолчанию отключены.
Чтобы использовать фрагменты, задайте аргумент командной строки
`enable-snippets`.
Недостатки использования фрагментов:
- *Сложность*. Чтобы использовать фрагменты, требуется:
- Понимать примитивы конфигурации Angie и реализовать правильную
конфигурацию Angie.
- Понимать, как ANIC генерирует конфигурацию Angie, чтобы фрагмент не
мешал другим функциям конфигурации.
- *Сниженная надежность*. Неправильный фрагмент делает конфигурацию
Angie недействительной, что приведет к ошибке при перезагрузке. Это
помешает применить какие-либо обновления конфигурации, включая
обновления для других ресурсов VirtualServer и VirtualServerRoute,
пока фрагмент не будет исправлен.
- *Последствия для безопасности*. Фрагменты предоставляют доступ к
примитивам конфигурации Angie, и эти примитивы не проверяются самим
ANIC. Например, через фрагмент можно настроить в Angie
произвольную отправку сертификатов TLS и ключей, используемых для
терминации TLS у ресурсов Ingress и VirtualServer.
Чтобы помочь отлавливать ошибки при использовании фрагментов, ANIC
сообщает об ошибках перезагрузки конфигурации в журналах, а
также в полях событий и состояния ресурсов VirtualServer и
VirtualServerRoute.
#### NOTE
Пока конфигурация Angie содержит недопустимый фрагмент,
Angie будет продолжать работать с последней допустимой конфигурацией.
### Валидация
Для ресурсов VirtualServer и VirtualServerRoute доступны два типа
валидации:
- *Структурная валидация* с помощью `kubectl` и сервера Kubernetes API.
- *Всесторонняя валидация* с помощью ANIC.
#### Структурная валидация
Пользовательские определения ресурсов для VirtualServer и VirtualServerRoute
включают структурную схему OpenAPI, которая описывает тип каждого поля этих
ресурсов.
Если вы попытаетесь создать (или обновить) ресурс с нарушением структурной
схемы (например, используете строковое значение для поля порта апстрима),
`kubectl` и сервер Kubernetes API отклонят такой ресурс:
- Пример проверки `kubectl`:
```console
kubectl apply -f cafe-virtual-server.yaml
error: error validating "cafe-virtual-server.yaml": error validating
data: ValidationError(VirtualServer.spec.upstreams[0].port): invalid
type for software.angie.k8s.v1.VirtualServer.spec.upstreams.port: got
"string", expected "integer"; if you choose to ignore these errors,
turn validation off with --validate=false
```
- Пример проверки сервера Kubernetes API:
```console
kubectl apply -f cafe-virtual-server.yaml --validate=false
The VirtualServer "cafe" is invalid: []: Invalid value:
map[string]interface {}{ ... }: validation failure list:
spec.upstreams.port in body must be of type integer: "string"
```
Если ресурс не отклонен (т. е. не нарушает структурную схему), ANIC
проверит его дополнительно.
#### Всесторонняя валидация
ANIC проверяет поля ресурсов VirtualServer и VirtualServerRoute.
Если ресурс недействителен, ANIC отклонит его: ресурс продолжит
существовать в кластере, но ANIC будет его игнорировать.
Вы можете проверить, успешно ли ANIC применил конфигурацию для
VirtualServer. Для нашего примера VirtualServer `cafe` мы можем запустить:
```console
kubectl describe vs cafe
. . .
Events:
Type Reason Age From Message
-----
Normal AddedOrUpdated 16s angie-ingress-controller Configuration for default/cafe was added or updated
```
Обратите внимание, что раздел "События" (Events) включает событие Normal с
причиной AddedOrUpdated, которое информирует нас о том, что конфигурация была
успешно применена.
Если вы создадите недопустимый ресурс, ANIC отклонит его и выдаст
событие Rejected. Например, если вы создадите VirtualServer `cafe` с двумя
серверами апстрима с одинаковым именем `tea`, вы получите:
```console
kubectl describe vs cafe
. . .
Events:
Type Reason Age From Message
-----
Warning Rejected 12s angie-ingress-controller VirtualServer default/cafe is invalid and was rejected: spec.upstreams[1].name: Duplicate value: "tea"
```
Обратите внимание, что раздел "События" (Events) включает предупреждающее
событие с указанием причины отклонения.
Кроме того, эта информация также доступна в поле `status` ресурса
VirtualServer. Обратите внимание на раздел `Status` VirtualServer:
```console
kubectl describe vs cafe
. . .
Status:
External Endpoints:
Ip: 12.13.23.123
Ports: [80,443]
Message: VirtualServer default/cafe is invalid and was rejected: spec.upstreams[1].name: Duplicate value: "tea"
Reason: Rejected
State: Invalid
```
ANIC проверяет ресурсы VirtualServerRoute аналогичным образом.
#### NOTE
Если вы внесете ошибку в существующий ресурс, ANIC отклонит
его и удалит соответствующую конфигурацию из Angie.
## Настройка с помощью ConfigMap
Вы можете дополнительно настроить конфигурацию Angie для ресурсов VirtualServer
и VirtualServerRoutes, используя `ConfigMap`. Поддерживается большинство
ключей ConfigMap, за следующими исключениями:
- `proxy-hide-headers`
- `proxy-pass-headers`
- `hsts`
- `hsts-max-age`
- `hsts-include-subdomains`
- `hsts-behind-proxy`
- `redirect-to-https`
- `ssl-redirect`
# https://angie.software/anic/docs/configuration/annotations.md
# Расширенная конфигурация с помощью аннотаций
Здесь объясняется, как включить расширенную функциональность ANIC с помощью аннотаций.
Ресурс Ingress может использовать базовые функции Angie, такие как маршрутизация
на основе хоста или пути и TLS-терминация. Расширенные функции, такие как
переписывание URI запроса или вставка дополнительных заголовков ответа, могут
быть включены с помощью аннотаций. Аннотации позволяют настраивать поведение
Angie для каждого Ingress-ресурса.
Помимо расширенных функций, аннотации необходимы для настройки поведения Angie,
например, установки значений таймаутов соединений.
Настройка также доступна через ресурсы [ConfigMap](https://angie.software//anic/docs/configuration/configmap-resource.md#configmap-resource):
аннотации имеют приоритет.
## Использование аннотаций
Этот пример использует аннотации для настройки конфигурации ресурса Ingress:
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress-with-annotations
annotations:
``angie.software/proxy-connect-timeout: "30s"
``angie.software/proxy-read-timeout: "20s"
``angie.software/client-max-body-size: "4m"
``angie.software/server-snippets: |
location / {
return 302 /coffee;
}
spec:
rules:
- host: cafe.example.com
http:
paths:
- path: /tea
pathType: Prefix
backend:
service:
name: tea-svc
port:
number: 80
- path: /coffee
pathType: Prefix
backend:
service:
name: coffee-svc
port:
number: 80
```
## Валидация
ANIC проверяет аннотации ресурсов Ingress. Если Ingress некорректен, ANIC
отклонит его: Ingress продолжит существовать в кластере, но ANIC будет его
игнорировать.
Вы можете проверить, успешно ли ANIC применил конфигурацию для ресурса Ingress.
Для примера Ingress `cafe-ingress-with-annotations` вы можете выполнить
следующую команду:
```console
$ kubectl describe ing cafe-ingress-with-annotations
```
```none
...
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal AddedOrUpdated 3s angie-ingress-controller Configuration for default/cafe-ingress-with-annotations was added or updated
```
Раздел событий включает событие Normal с причиной AddedOrUpdated, которое
сообщает нам, что конфигурация была успешно применена.
Если вы создадите некорректный Ingress, ANIC отклонит его и сгенерирует событие
Rejected. Например, если вы создадите Ingress `cafe-ingress-with-annotations`
с аннотацией `angie.software/redirect-to-https`, установленной на `yes please`
вместо `true`, вы получите:
```console
$ kubectl describe ing cafe-ingress-with-annotations
```
```text
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning Rejected 13s angie-ingress-controller annotations.``angie.software/redirect-to-https: Invalid value: "yes please": must be a boolean
```
Обратите внимание, что раздел событий включает событие Warning с причиной
Rejected.
#### NOTE
Если вы сделаете существующий Ingress некорректным, ANIC отклонит его и
удалит соответствующую конфигурацию из ANIC.
## Сводка аннотаций
В таблице ниже приведены доступные аннотации.
### Общая настройка
| Аннотация | Ключ ConfigMap | Описание | Значение по умолчанию | Пример |
|-------------------------------------------|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| `angie.software/proxy-connect-timeout` | `proxy-connect-timeout` | Устанавливает значение для директив [proxy_connect_timeout](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-connect-timeout)
и [grpc_connect_timeout](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-connect-timeout). | `60s` | |
| `angie.software/proxy-read-timeout` | `proxy-read-timeout` | Устанавливает значение для директив [proxy_read_timeout](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-read-timeout)
и [grpc_read_timeout](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-read-timeout). | `60s` | |
| `angie.software/proxy-send-timeout` | `proxy-send-timeout` | Устанавливает значение для директив [proxy_send_timeout](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-send-timeout)
и [grpc_send_timeout](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-send-timeout). | `60s` | |
| `angie.software/client-max-body-size` | `client-max-body-size` | Устанавливает значение для директивы [client_max_body_size](https://angie.software//angie/docs/configuration/modules/http/index.md#client-max-body-size) (ограничивает размер тела запроса клиента).
Alias для `nginx.ingress.kubernetes.io/proxy-body-size`. | `1m` | |
| `angie.software/proxy-body-size` | `proxy-body-size` | Устанавливает максимально допустимый размер тела запроса клиента, передаваемого прокси-сервером дальше. См. также [client_max_body_size](https://angie.software//angie/docs/configuration/modules/http/index.md#client-max-body-size). | `1m` | |
| `angie.software/proxy-buffering` | `proxy-buffering` | Включает или отключает [буферизацию ответов](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-buffering)
от проксируемого сервера. Alias для `nginx.ingress.kubernetes.io/proxy-buffering`. | `True` | |
| `angie.software/proxy-buffers` | `proxy-buffers` | Устанавливает значение для директивы [proxy_buffers](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-buffers). Alias для `nginx.ingress.kubernetes.io/proxy-buffers-number`. | Зависит от платформы. | |
| `angie.software/proxy-buffer-size` | `proxy-buffer-size` | Устанавливает значение для директив [proxy_buffer_size](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-buffer-size). Alias для `nginx.ingress.kubernetes.io/proxy-buffer-size`.
и [grpc_buffer_size](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-buffer-size). | Зависит от платформы. | |
| `angie.software/proxy-max-temp-file-size` | `proxy-max-temp-file-size` | Устанавливает значение для директивы [proxy_max_temp_file_size](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-max-temp-file-size). Alias для `nginx.ingress.kubernetes.io/proxy-max-temp-file-size`. | `1024m` | |
| `angie.software/server-tokens` | `server-tokens` | Включает или отключает директиву [server_tokens](https://angie.software//angie/docs/configuration/modules/http/index.md#server-tokens).
Кроме того, с Angie можно указать строковое значение, включая пустую строку,
что отключает вывод поля `Server`. | `True` | |
| `angie.software/path-regex` | Нет | Включает модификаторы регулярных выражений для параметра пути Ingress.
Это соответствует директиве Angie [location](https://angie.software//angie/docs/configuration/modules/http/index.md#location).
Можно указать одно из значений: "case_sensitive", "case_insensitive" или
"exact". Аннотация применяется к ресурсу Ingress и его путям. При
использовании Master и Minion Ingresses (т.е. Mergeable Ingresses) эту
аннотацию можно указывать для Minion-типов. Аннотация `path-regex`,
указанная для Master, игнорируется и не влияет на пути, определенные в
Minions. Подробнее см. также [статью о сопоставлении путей Ingress-ресурсов с помощью регулярных выражений](https://angie.software//anic/docs/common-tasks-and-examples/path-regex-annotation-for-ingresses.md#path-regex-annotation-for-ingresses). | Нет | |
| `angie.software/configmap` | Нет | Позволяет задать конкретный ConfigMap для настройки ресурса Ingress. Заданный ConfigMap будет иметь приоритет над глобальным. В случае, если глобальный и заданный ConfigMap совпадают, применится заданный. Пример: `angie.software/configmap: "namespace/configmap"` | `False` | См. [переопределение ConfigMap для ресурса Ingress](https://angie.software//anic/docs/configuration/configmap-resource.md#annotation-configmap). |
### Манипуляция URI и заголовками запросов
| Аннотация | Ключ ConfigMap | Описание | Значение по умолчанию | Пример |
|-------------------------------------|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|----------|
| `angie.software/proxy-hide-headers` | `proxy-hide-headers` | Устанавливает значение одной или нескольких директив [proxy_hide_header](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-hide-header). Пример: `"`angie.software/proxy-hide-headers": "header-a,header-b"`` | Нет | |
| `angie.software/proxy-pass-headers` | `proxy-pass-headers` | Устанавливает значение одной или нескольких директив [proxy_pass_header](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass-header). Пример: `"`angie.software/proxy-pass-headers": "header-a,header-b"`` | Нет | |
| `angie.software/rewrites` | Нет | Конфигурирует перезапись URI с использованием директивы [proxy_pass](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass). | Нет | |
### Аутентификация и SSL/TLS
| Аннотация | Ключ ConfigMap | Описание | Значение по умолчанию | Пример |
|------------------------------------------|---------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|----------|
| `angie.software/redirect-to-https` | `redirect-to-https` | Устанавливает правило перенаправления 301 на основе значения заголовка
`http_x_forwarded_proto` в серверном блоке, чтобы заставить входящий
трафик проходить через HTTPS. Полезно при SSL-терминации в
балансировщике нагрузки перед ANIC. | `False` | |
| `ingress.kubernetes.io/ssl-redirect` | `ssl-redirect` | Устанавливает некондиционное правило перенаправления 301 для всего входящего HTTP трафика, чтобы заставить входящий трафик проходить через HTTPS. | `True` | |
| `angie.software/hsts` | `hsts` | Включает [HTTP Strict Transport Security (HSTS)](https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/): заголовок HSTS добавляется к ответам от проксируемых серверов. В заголовок включается директива `preload`. | `False` | |
| `angie.software/hsts-max-age` | `hsts-max-age` | Устанавливает значение директивы `max-age` заголовка HSTS. | `2592000` (1 месяц) | |
| `angie.software/hsts-include-subdomains` | `hsts-include-subdomains` | Добавляет директиву `includeSubDomains` в заголовок HSTS. | `False` | |
| `angie.software/hsts-behind-proxy` | `hsts-behind-proxy` | Включает HSTS на основе значения заголовка запроса
`http_x_forwarded_proto`. Следует использовать, только когда в
балансировщике нагрузки (прокси) перед ANIC настроена TLS-терминация.
#### NOTE
Для управления перенаправлением с HTTP на HTTPS настройте аннотацию
`angie.software/redirect-to-https`. | `False` | |
| `angie.software/basic-auth-secret` | Нет | Указывает ресурс Secret с списком пользователей для HTTP Basic аутентификации. | Нет | |
| `angie.software/basic-auth-realm` | Нет | Указывает область. | Нет | |
### Прослушиватели
| Аннотация | Ключ ConfigMap | Описание | Значение по умолчанию | Пример |
|-----------------------------------|------------------|------------------------------------------------------------|-------------------------|----------|
| `angie.software/listen-ports` | Нет | Конфигурирует HTTP порты, на которых Angie будет слушать. | `[80]` | |
| `angie.software/listen-ports-ssl` | Нет | Конфигурирует HTTPS порты, на которых Angie будет слушать. | `[443]` | |
### Бэкенд-сервисы (апстримы)
| Аннотация | Ключ ConfigMap | Описание | Значение по умолчанию | Пример |
|------------------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------|----------|
| `nginx.ingress.kubernetes.io/backend-protocol` | Нет | Устанавливает протокол для взаимодействия с backend-подами (службами) в Kubernetes. | Нет | |
| `angie.software/lb-method` | `lb-method` | Устанавливает [метод балансировки нагрузки](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).
Для использования метода round-robin укажите `"round_robin"`. | `"random two least_conn"` | |
| `angie.software/ssl-services` | Нет | Включает HTTPS или gRPC через SSL при подключении к конечным точкам сервисов. | Нет | |
| `angie.software/grpc-services` | Нет | Включает gRPC для сервисов.
#### NOTE
Требует HTTP/2 (см. ключ `http2` в ConfigMap);
работает только для Ingress с включенной TLS-терминацией. | Нет | |
| `angie.software/websocket-services` | Нет | Включает WebSocket для сервисов. | Нет | |
| `angie.software/max-fails` | `max-fails` | Устанавливает значение параметра `max_fails` директивы [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server). | `1` | |
| `angie.software/max-conns` | Нет | Устанавливает значение параметра `max_conns` директивы [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server). | `0` | |
| `angie.software/upstream-zone-size` | `upstream-zone-size` | Устанавливает размер [зоны разделяемой памяти](https://angie.software/configuration/modules/http_upstream/#zone) для апстрима. Для Angie специальное значение 0 отключает зоны общей памяти. Для Angie зоны общей памяти требуются и не могут быть отключены. Специальное значение 0 будет проигнорировано. | `256K` | |
| `angie.software/fail-timeout` | `fail-timeout` | Устанавливает значение параметра `fail_timeout` директивы `u_server`. | `10s` | |
| `angie.software/sticky-cookie-services` | Нет | Конфигурирует сохранение сеансов. | Нет | |
| `angie.software/keepalive` | `keepalive` | Устанавливает значение директивы [keepalive](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive). Обратите внимание,
что `proxy_set_header Connection "";` добавляется в сгенерированную
конфигурацию, когда значение > 0. | `0` | |
| `angie.software/health-checks` | Нет | Включает активные проверки состояния. | `False` | |
| `angie.software/health-checks-mandatory` | Нет | Конфигурирует активные проверки состояния как обязательные. | `False` | |
| `angie.software/health-checks-mandatory-queue` | Нет | Когда активные проверки состояния обязательны, создает очередь, в которой входящие запросы временно хранятся, пока Angie проверяет состояние конечных точек после перезагрузки конфигурации. | `0` | |
| `angie.software/slow-start` | Нет | Устанавливает [период медленного запуска сервера](https://angie.software/configuration/modules/http_upstream/#server)
для апстрима. По умолчанию медленный запуск активируется после того, как
сервер становится [доступным](https://angie.software/configuration/modules/http_upstream/#server)
или
[здоровым](https://angie.software/configuration/modules/http_upstream_probe/).
Для включения медленного запуска для новоназначенных серверов настройте
[обязательные активные проверки состояния](https://angie.software/configuration/modules/http_upstream_probe/). | `"0s"` | |
| `angie.software/use-cluster-ip` | Нет | Включает использование IP-адреса и порта кластера сервиса вместо
поведения по умолчанию, когда используются IP и порт подов. Когда это
поле включено, поля, которые настраивают поведение Angie, связанное с
несколькими апстримами (такими как `lb-method` и `next-upstream`), не
будут иметь эффекта, так как ANIC настроит Angie только с одним
апстримом, который будет соответствовать IP кластера сервиса. | `False` | |
### Ограничение скорости
| Аннотация | Ключ ConfigMap | Описание | Значение по умолчанию | Пример |
|----------------------------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|-----------------------|
| `angie.software/limit-req-rate` | Нет | Включает ограничение скорости запросов для этого Ingress, создавая
[limit_req_zone](https://angie.software//angie/docs/configuration/modules/http/http_limit_req.md#limit-req-zone)
и применяя [Limit Req](https://angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req)
для каждого location. Все серверы/location одного Ingress используют одну
зону. Должен иметь единицу r/s или r/m. | Нет | 200r/s |
| `angie.software/limit-req-key` | Нет | Ключ, к которому применяется ограничение скорости. Может содержать текст, переменные или их комбинацию. Переменные должны быть окружены ${}. | ${binary_remote_addr} | ${binary_remote_addr} |
| `angie.software/limit-req-zone-size` | Нет | Конфигурирует размер созданной [limit_req_zone](https://angie.software//angie/docs/configuration/modules/http/http_limit_req.md#limit-req-zone). | 10m | 20m |
| `angie.software/limit-req-delay` | Нет | Конфигурирует параметр delay директивы [Limit Req](https://angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req). | 0 | 100 |
| `angie.software/limit-req-no-delay` | Нет | Конфигурирует параметр nodelay директивы [Limit Req](https://angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req). | false | true |
| `angie.software/limit-req-burst` | Нет | Конфигурирует параметр burst директивы [Limit Req](https://angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req). | Нет | 100 |
| `angie.software/limit-req-dry-run` | Нет | Включает режим проверки. В этом режиме ограничение скорости не применяется, но количество избыточных запросов учитывается, как обычно, в зоне общей памяти. | false | true |
| `angie.software/limit-req-log-level` | Нет | Устанавливает желаемый уровень логирования для случаев, когда сервер отказывается обрабатывать запросы из-за превышения скорости или задержек в обработке запросов. Разрешенные значения: info, notice, warn или error. | error | info |
| `angie.software/limit-req-reject-code` | Нет | Устанавливает код состояния, который возвращается в ответ на отклоненные запросы. Должен находиться в диапазоне 400..599. | 429 | 503 |
| `angie.software/limit-req-scale` | Нет | Включает постоянное ограничение скорости, деля настроенное значение
скорости на количество подов Ingress, в настоящее время
обслуживающих трафик. Эта корректировка обеспечивает постоянство
ограничения скорости, даже если количество подов изменяется из-за
автоскейлинга.
#### NOTE
Это не будет работать правильно, если запросы от клиента
не распределяются равномерно между всеми подами Ingress
(привязка сеансов, длительные TCP-соединения с множеством запросов и
т.д.). В таких случаях лучшие результаты даст
использование функции синхронизации зон Angie. | false | true |
### Фрагменты и пользовательские шаблоны
| Аннотация | Ключ ConfigMap | Описание | Значение по умолчанию | Пример |
|------------------------------------|---------------------|---------------------------------------------------------------|-------------------------|----------|
| `angie.software/location-snippets` | `location-snippets` | Устанавливает пользовательский фрагмент в контексте location. | Нет | |
| `angie.software/server-snippets` | `server-snippets` | Устанавливает пользовательский фрагмент в контексте server. | Нет | |
# https://angie.software/anic/docs/logging-and-monitoring.md
# Журналы и мониторинг
ANIC поддерживает мониторинг с помощью метрик Prometheus и ведение журналов.
> [Просмотр журналов](https://angie.software//anic/docs/logging-and-monitoring/logging.md#logging-anic)
> [Просмотр состояния сервера](https://angie.software//anic/docs/logging-and-monitoring/status-page.md#status-page-anic)
> [Просмотр состояния ресурсов](https://angie.software//anic/docs/logging-and-monitoring/reporting-resources-status.md#reporting-resources-status)
# https://angie.software/anic/docs/logging-and-monitoring/logging.md
# Просмотр журналов
В ANIC можно посмотреть журнал процесса Ingress Controller (процесса, который генерирует конфигурацию Angie и перезагружает Angie для ее применения), а также журнал доступа и журнал ошибок Angie. Все записи идут в стандартный вывод и стандартный поток ошибок процесса Ingress Controller. Чтобы просмотреть журнал, вы можете выполнить команду `kubectl logs` для пода ANIC.
Например:
```yaml
kubectl logs -n angie-ingress
```
## Журнал процесса Ingress Controller
Журнал процесса Ingress Controller можно настроить с помощью [аргумента командной строки](https://angie.software//anic/docs/configuration/command-line-arguments.md#v-value) `-v`, который задает уровень детализации журнала. Значение по умолчанию — `1`, при этом значении записывается минимальное количество событий. Значение `3` полезно для устранения неполадок: вы сможете увидеть, как Ingress Controller получает обновления от Kubernetes API, генерирует конфигурацию Angie и перезагружает Angie.
## Журналы Angie
Angie включает два журнала:
- *Журнал доступа*. В этот журнал Angie записывает информацию о запросах клиентов сразу после обработки запроса. Журнал доступа настраивается через [ключи ConfigMap](https://angie.software//anic/docs/configuration/configmap-resource.md#logging-configmap): `log-format` для HTTP- и HTTPS-трафика и `stream-log-format` для сквозного трафика TCP, UDP и TLS. Вы можете отключить запись журнала доступа с помощью ключа `access-log-off`.
- *Журнал ошибок*. В этот журнал Angie записывает информацию о возникших проблемах различного уровня критичности. Этот журнал настраивается через ключ `error-log-level` в [ConfigMap](https://angie.software//anic/docs/configuration/configmap-resource.md#logging-configmap). Чтобы включить отладочное логирование, установите значение `debug`, а также задайте аргумент командной строки `-angie-debug`. Angie будет запущен с отладочной версией бинарного файла `angie-debug`.
# https://angie.software/anic/docs/logging-and-monitoring/status-page.md
# Просмотр состояния сервера
Angie поставляется со [страницей статуса Stub Status](https://angie.software/configuration/modules/http/http_stub_status/), которая отображает основные метрики.
## Доступ к Stub Status
Необходимые условия:
1. Stub Status должен быть включен по умолчанию. Убедитесь, что [аргумент командной строки](https://angie.software//anic/docs/configuration/command-line-arguments.md#command-line-arguments) `angie-status` задан как true.
2. По умолчанию Stub Status доступен на порту 8080. Порт можно изменить с помощью аргумента командной строки `angie-status-port`. Если ваш порт отличается от 8080, измените команду kubectl proxy ниже.
Чтобы открыть страницу статуса, выполните следующие действия:
1. Используйте команду `kubectl port-forward`, чтобы перенаправить соединения с порта 8080 на вашем локальном компьютере на порт 8080 пода ANIC (замените `` на фактическое имя пода):
> ```yaml
> kubectl port-forward 8080:8080 --namespace=angie-ingress
> ```
1. Откройте браузер по адресу [http://127.0.0.1:8080/stub_status](http://127.0.0.1:8080/stub_status).
Чтобы получить доступ к stub status извне (без kubectl port-forward), выполните следующие действия:
1. Настройте с помощью [аргумента командной строки](https://angie.software//anic/docs/configuration/command-line-arguments.md#command-line-arguments) `-angie-status-allow-cidrs` блоками IP/CIDR, для которых вы хотите разрешить доступ к статусу. По умолчанию доступ разрешен для `127.0.0.1,::1`.
2. Используйте IP/порт, через который доступен под ANIC, чтобы подключиться к странице статуса по пути `/stub_status`.
# https://angie.software/anic/docs/logging-and-monitoring/reporting-resources-status.md
# Просмотр состояния ресурсов
## Ресурсы Ingress
Ресурс Ingress может иметь состояние, куда входит адрес (IP-адрес или DNS-имя),
через который становятся общедоступными узлы этого ресурса Ingress. Адрес можно
видеть в выходных данных команды `kubectl get ingress` в столбце ADDRESS, как
показано ниже:
```default
$ kubectl get ingresses
NAME HOSTS ADDRESS PORTS AGE
myapp-ingress myapp.example.com 12.13.23.123 80, 443 2m
```
ANIC должен быть сконфигурирован таким образом, чтобы
сообщать о состоянии Ingress:
1. Используйте флаг командной строки [-report-ingress-status](https://angie.software//anic/docs/configuration/command-line-arguments.md#report-ingress-status).
2. Определите источник для внешнего адреса. Это может быть:
- Определенный пользователем адрес, указанный в ключе ConfigMap
`external-status-address`.
- Служба типа LoadBalancer, настроенная с внешним IP-адресом или без
него и указанная с помощью флага командной строки
`-external-service`.
См. документацию по [ключам ConfigMap](https://angie.software//anic/docs/configuration/configmap-resource.md#configmap-resource)
и [аргументам командной строки](https://angie.software//anic/docs/configuration/command-line-arguments.md#command-line-arguments).
#### NOTE
При завершении работы ANIC не очищает статус ресурсов Ingress.
## Ресурсы VirtualServer и VirtualServerRoute
Ресурс VirtualServer или VirtualServerRoute содержит поле состояния с
информацией о состоянии ресурса и IP-адрес, через который становятся
общедоступными узлы этого ресурса. Вы можете увидеть состояние в
выходных данных команд `kubectl get virtualservers` или
`kubectl get virtualserverroutes`, как показано ниже:
```default
$ kubectl get virtualservers
NAME STATE HOST IP PORTS AGE
myapp Valid myapp.example.com 12.13.23.123 [80,443] 34s
```
Чтобы просмотреть внешний адрес имени узла, связанный с ресурсом
VirtualServer, используйте параметр `-o wide`:
```default
$ kubectl get virtualservers -o wide
NAME STATE HOST IP EXTERNALHOSTNAME PORTS AGE
mysite Valid mysite.example.com ae430f41a1a0042908655abcdefghijkl-12345678.eu-west-2.elb.amazonaws.com [80,443] 106s
```
#### NOTE
При наличии нескольких адресов отображается только первый из них.
Чтобы просмотреть дополнительные адреса или дополнительную информацию о
статусе ресурса, используйте следующую команду:
```default
$ kubectl describe virtualserver
. . .
Status:
External Endpoints:
Ip: 12.13.23.123
Ports: [80,443]
Message: Configuration for myapp/myapp was added or updated
Reason: AddedOrUpdated
State: Valid
```
### Спецификация состояния
Следующие поля отображаются как в статусе VirtualServer, так и в статусе
VirtualServerRoute:
| Поле | Описание | Тип |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------|
| `State` | Текущее состояние ресурса. Возможные значения: `Valid` (допустимо),
`Warning` (внимание) и `Invalid` (недопустимо). Дополнительные
сведения см. в поле `message`. | `string` |
| `Reason` | Причина последнего обновления. | `string` |
| `Message` | Дополнительная информация о состоянии. | `string` |
| `ExternalEndpoints` | Список внешних конечных точек, для которых хосты ресурса являются
общедоступными. | [externalEndpoint[ ]](#externalendpoint) |
Следующее поле отображается только в состоянии VirtualServerRoute:
| Поле | Описание | Тип |
|----------------|---------------------------------------------------------------------------------------------------|----------|
| `ReferencedBy` | VirtualServer, который ссылается на этот VirtualServerRoute.
Формат: `пространство имен/имя`. | `string` |
### ExternalEndpoint
| Поле | Описание | Тип |
|------------|--------------------------------------------------------|----------|
| `IP` | Внешний IP-адрес. | `string` |
| `Hostname` | Адрес имени узла внешнего балансировщика LoadBalancer. | `string` |
| `Ports` | Список внешних портов. | `string` |
ANIC должен быть настроен таким образом, чтобы сообщать о
состоянии VirtualServer или VirtualServerRoute.
Если вы хотите, чтобы ANIC сообщал о
`внешних конечных точках`, определите источник для внешнего адреса.
Это может быть:
- Определенный пользователем адрес, указанный в ключе ConfigMap
`external-status-address`.
- Служба типа LoadBalancer, настроенная с внешним IP-адресом или без
него и указанная с помощью флага командной строки
`-external-service`.
См. документацию по [ключам ConfigMap](https://angie.software//anic/docs/configuration/configmap-resource.md#configmap-resource)
и [аргументам командной строки](https://angie.software//anic/docs/configuration/command-line-arguments.md#command-line-arguments).
Остальные поля будут включаться в отчет и без настроенного внешнего адреса.
#### NOTE
При завершении работы ANIC не очищает статус ресурсов VirtualServer и
VirtualServerRoute.
## Ресурсы Policy
Ресурс Policy включает в себя поле статуса с информацией о состоянии
ресурса. Вы можете увидеть статус в выходных данных команды
`kubectl get policy`, как показано ниже:
```default
$ kubectl get policy
NAME STATE AGE
webapp-policy Valid 30s
```
Чтобы просмотреть дополнительные адреса или дополнительную информацию о
статусе ресурса, используйте следующую команду:
```default
$ kubectl describe policy
. . .
Status:
Message: Configuration for default/webapp-policy was added or updated
Reason: AddedOrUpdated
State: Valid
```
### Спецификация состояния
В состоянии Policy отображаются следующие поля:
| Поле | Описание | Тип |
|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
| `State` | Текущее состояние ресурса. Возможные значения: `Valid` (допустимо)
или `Invalid` (недопустимо). Дополнительные сведения см. в поле
`message`. | `string` |
| `Reason` | Причина последнего обновления. | `string` |
| `Message` | Дополнительная информация о состоянии. | `string` |
## Ресурсы TransportServer
Ресурс TransportServer включает в себя поле состояния с информацией о
состоянии ресурса. Вы можете увидеть его в выходных данных команды
`kubectl get transportserver`, как показано ниже:
```default
$ kubectl get transportserver
NAME STATE REASON AGE
dns-tcp Valid AddedOrUpdated 47m
```
Чтобы просмотреть дополнительные адреса или дополнительную информацию о
статусе ресурса, используйте следующую команду:
```default
$ kubectl describe transportserver
. . .
Status:
Message: Configuration for default/dns-tcp was added or updated
Reason: AddedOrUpdated
State: Valid
```
### Спецификация состояния
В состоянии TransportServer отображаются следующие поля:
| Поле | Описание | Тип |
|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
| `State` | Текущее состояние ресурса. Возможные значения: `Valid` (допустимо),
`Warning` (внимание) и `Invalid` (недопустимо).
Дополнительные сведения см. в поле `message`. | `string` |
| `Reason` | Причина последнего обновления. | `string` |
| `Message` | Дополнительная информация о состоянии. | `string` |
# https://angie.software/anic/docs/common-tasks-and-examples.md
# Типовые задачи
В этом разделе собраны примеры настройки ANIC под разные задачи.
> [Создание кастомных страниц ошибок](https://angie.software//anic/docs/common-tasks-and-examples/custom-error-page.md#custom-error-page)
> [Сопоставление путей с помощью регулярных выражений](https://angie.software//anic/docs/common-tasks-and-examples/path-regex-annotation-for-ingresses.md#path-regex-annotation-for-ingresses)
# https://angie.software/anic/docs/common-tasks-and-examples/custom-error-page.md
# Создание кастомных страниц ошибок
В ANIC можно настроить кастомные страницы ошибок, например c более информативными сообщениями для пользователей (для статусов наподобие 502).
Добавить кастомную страницу можно двумя способами:
- пересобрать образ ANIC с новой страницей;
- настроить ConfigMap без пересборки образа ANIC.
## Пересборка образа ANIC с кастомной страницей
Этот вариант предполагает создание нового Docker-образа ANIC, который включает кастомную страницу ошибки.
Такой вариант подойдет, если кастомная страница ошибки редко меняется и ее удобно включить в образ.
Выполните следующие шаги:
1. Создайте Dockerfile и добавьте в него новую страницу ошибки:
```dockerfile
FROM anic.docker.angie.software/anic:latest
COPY 502.html /usr/share/angie/html/
```
2. Соберите и загрузите новый образ в кластер (см. [Установка с помощью Helm](https://angie.software//anic/docs/installation/installation-with-helm.md#installation-with-helm)).
3. Разверните обновленный образ в кластере.
4. Добавьте в Ingress-ресурс аннотацию для использования кастомной страницы ошибки:
```yaml
annotations:
angie.software/server-snippets: |
error_page 502 /502.html;
location = /502.html {
root /usr/share/angie/html;
internal;
}
```
#### NOTE
Также можно использовать ConfigMap, тогда правило будет применяться ко всем серверам.
Этот способ подходит как для Ingress-ресурса, так и для VirtualServer.
## Использование ConfigMap без пересборки образа
Если нет возможности пересобрать образ ANIC, можно поместить страницу ошибки в под через ConfigMap.
Также этот способ удобен, если требуется оперативно менять содержимое страницы ошибки.
Выполните следующие шаги:
1. Создайте ConfigMap с HTML-страницей ошибки:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: error-page
namespace: angie
data:
502.html: |
ERROR PAGE
ERROR PAGE
```
2. Добавьте в файл `values.yaml` эту ConfigMap:
```yaml
volumes:
- name: error-page
configMap:
name: error-page
## The volumeMounts of the Ingress Controller pods.
volumeMounts: []
- name: error-page
mountPath: /usr/share/angie/html/custom_error
```
3. Добавьте в Ingress-ресурс аннотацию:
```yaml
annotations:
angie.software/server-snippets: |
error_page 502 /502.html;
location = /502.html {
root /usr/share/angie/html/custom_error;
internal;
}
```
Этот способ подходит как для Ingress-ресурса, так и для VirtualServer.
# https://angie.software/anic/docs/common-tasks-and-examples/path-regex-annotation-for-ingresses.md
# Сопоставление путей с помощью регулярных выражений
Здесь показано, как настроить пути в ресурсах Ingress и Mergeable Ingress
с помощью [аннотации](https://angie.software//anic/docs/configuration/annotations.md#annotations) `path-regex` и регулярных выражений.
Для аннотации `path-regex` возможны следующие значения:
- `case_insensitive` - этот модификатор удобно использовать для маршрутизации,
когда регистр не важен, и вы хотите избежать проблем, например с неправильным вводом URL пользователями
(запросы на `/Tea`, `/tea`, и `/TEA` будут направлены на один и тот же ресурс).
- `case_sensitive` - этот модификатор можно использовать для более строгого контроля маршрутизации,
когда регистр имеет значение, например в API (`/User/123` и `/user/123` могут означать разные сущности).
Рекомендуем также ознакомиться с [работой директивы location в документации
Angie](https://angie.software//angie/docs/configuration/modules/http/index.md#location).
## Пример настройки ресурса Ingress
Чтобы настроить регулярные выражения для путей ресурса Ingress, выполните следующие шаги:
1. Добавьте в файл `cafe-ingress.yaml` аннотацию `angie.software/path-regex` со значением `case_sensitive`.
### Пример
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress
annotations:
angie.software/path-regex: "case_sensitive"
spec:
tls:
- hosts:
- cafe.example.com
secretName: cafe-secret
rules:
- host: cafe.example.com
http:
paths:
- path: /tea/[A-Z0-9]
backend:
serviceName: tea-svc
servicePort: 80
- path: /coffee/[A-Z0-9]
backend:
serviceName: coffee-svc
servicePort: 80
```
2. Выполните команду:
```console
kubectl create -f cafe-ingress.yaml
```
Пути `tea` и `coffee` в конфигурации Angie будут выглядеть следующим образом:
```nginx
location ~ "^/tea/[A-Z0-9]"
```
```nginx
location ~ "^/coffee/[A-Z0-9]"
```
#### NOTE
Обратите внимание, что модификатор регулярного выражения `case_sensitive` применяется ко всем путям.
3. Если вы хотите изменить значение на `case_insensitive`, обновите файл.
### Пример
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress
annotations:
angie.software/path-regex: "case_insensitive"
spec:
tls:
- hosts:
- cafe.example.com
secretName: cafe-secret
rules:
- host: cafe.example.com
http:
paths:
- path: /tea/[A-Z0-9]
backend:
serviceName: tea-svc
servicePort: 80
- path: /coffee/[A-Z0-9]
backend:
serviceName: coffee-svc
servicePort: 80
```
Теперь пути `/tea/[A-Z0-9]` и `/coffee/[A-Z0-9]` в конфигурации Angie будут выглядеть так:
```nginx
location ~* "^/tea/[A-Z0-9]"
```
```nginx
location ~* "^/coffee/[A-Z0-9]"
```
#### NOTE
Обратите внимание, что модификатор регулярного выражения `case_insensitive` применяется ко всем путям.
## Пример настройки ресурса Mergeable Ingress
### Создание Master Ingress и Minion Ingress
1. Создайте Master Ingress в файле `cafe-master.yaml`.
### Пример
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress-master
annotations:
angie.software/mergeable-ingress-type: "master"
spec:
ingressClassName: angie
tls:
- hosts:
- cafe.example.com
secretName: cafe-secret
rules:
- host: cafe.example.com
```
2. Выполните команду:
```console
kubectl create -f cafe-master.yaml
```
3. Проверьте, что Master Ingress создан:
```console
kubectl get ingress cafe-ingress-master
NAME CLASS HOSTS PORTS AGE
cafe-ingress-master angie cafe.example.com 80, 443 29s
```
```console
kubectl describe ingress cafe-ingress-master
Name: cafe-ingress-master
Labels:
Namespace: default
Address:
Ingress Class: angie
Default backend:
TLS:
cafe-secret terminates cafe.example.com
Rules:
Host Path Backends
---- ---- --------
* *
Annotations: angie.software/mergeable-ingress-type: master
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal AddedOrUpdated 62s angie-ingress-controller Configuration for default/cafe-ingress-master was added or updated
```
4. Создайте первый Minion Ingress для `tea` в файле `tea-minion.yaml`.
### Пример
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress-tea-minion
annotations:
angie.software/mergeable-ingress-type: "minion"
spec:
ingressClassName: angie
rules:
- host: cafe.example.com
http:
paths:
- path: /tea
pathType: Prefix
backend:
service:
name: tea-svc
port:
number: 80
```
5. Выполните команду:
```console
kubectl create -f tea-minion.yaml
```
6. Проверьте, что Minion Ingress создан:
```console
kubectl get ingress cafe-ingress-tea-minion
NAME CLASS HOSTS ADDRESS PORTS AGE
cafe-ingress-tea-minion angie cafe.example.com 80 23m
```
```console
kubectl describe ingress cafe-ingress-tea-minion
Name: cafe-ingress-tea-minion
Labels:
Namespace: default
Address:
Ingress Class: angie
Default backend:
Rules:
Host Path Backends
---- ---- --------
cafe.example.com
/tea tea-svc:80 (10.244.0.6:8080,10.244.0.7:8080,10.244.0.8:8080)
Annotations: angie.software/mergeable-ingress-type: minion
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal AddedOrUpdated 24m angie-ingress-controller Configuration for default/cafe-ingress-tea-minion was added or updated
```
7. Создайте второй Minion Ingress для `coffee` в файле `coffee-minion.yaml`.
### Пример
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress-coffee-minion
annotations:
angie.software/mergeable-ingress-type: "minion"
spec:
ingressClassName: angie
rules:
- host: cafe.example.com
http:
paths:
- path: /coffee
pathType: Prefix
backend:
service:
name: coffee-svc
port:
number: 80
```
8. Выполните команду:
```console
kubectl create -f coffee-minion.yaml
```
9. Проверьте, что Minion Ingress создан:
```console
kubectl get ingress cafe-ingress-coffee-minion
NAME CLASS HOSTS ADDRESS PORTS AGE
cafe-ingress-coffee-minion angie cafe.example.com 80 5m21s
```
```console
kubectl describe ingress cafe-ingress-coffee-minion
Name: cafe-ingress-coffee-minion
Labels:
Namespace: default
Address:
Ingress Class: angie
Default backend:
Rules:
Host Path Backends
---- ---- --------
cafe.example.com
/coffee coffee-svc:80 (10.244.0.6:8080,10.244.0.7:8080,10.244.0.8:8080)
Annotations: angie.software/mergeable-ingress-type: minion
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal AddedOrUpdated 5m52s angie-ingress-controller Configuration for default/cafe-ingress-coffee-minion was added or updated
```
Теперь у вас есть Master Ingress и два Minion Ingress. Два Minion Ingress определяются путями `/tea` и `/coffee`.
### Модификация путей с помощью регулярных выражений
Ниже показано, как изменить пути `/tea` и `/coffee` с помощью регулярных выражений.
1. Добавьте аннотацию `path-regex` со значением `case_insensitive`
в Minion Ingress (`tea`) и измените путь с помощью
регулярных выражений (в примере ниже: `/tea/[A-Z0-9]`).
### Пример
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress-tea-minion
annotations:
angie.software/mergeable-ingress-type: "minion"
angie.software/path-regex: "case_insensitive"
spec:
ingressClassName: angie
rules:
- host: cafe.example.com
http:
paths:
- path: /tea/[A-Z0-9]
pathType: Prefix
backend:
service:
name: tea-svc
port:
number: 80
```
2. Примените изменения:
```console
kubectl apply -f tea-minion.yaml
```
3. Проверьте, что изменения применились:
```console
kubectl describe ingress cafe-ingress-tea-minion
Name: cafe-ingress-tea-minion
Labels:
Namespace: default
Address:
Ingress Class: angie
Default backend:
Rules:
Host Path Backends
---- ---- --------
cafe.example.com
/tea/[A-Z0-9] tea-svc:80 (10.244.0.6:8080,10.244.0.7:8080,10.244.0.8:8080)
Annotations: angie.software/mergeable-ingress-type: minion
angie.software/path-regex: case_insensitive
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal AddedOrUpdated 47s (x2 over 34m) angie-ingress-controller Configuration for default/cafe-ingress-tea-minion was added or updated
```
Добавленная аннотация `path-regex` обновляет путь `/tea/[A-Z0-9]`
с использованием модификатора регулярного выражения `case_insensitive`.
Обновленный путь (`location`) в конфигурационном файле Angie будет выглядеть так:
```nginx
location ~* "^/tea/[A-Z0-9]"
```
#### NOTE
Обратите внимание, что аннотация `path-regex` применяется только к путям, определенным в соответствующем Minion Ingress (`tea`). Пути, определенные во втором Minion Ingress (`coffee`), не меняются.
4. Аналогичным образом используйте модификатор регулярного выражения `case_sensitive` для второго Minion Ingress (`coffee`) в файле `coffee-minion.yaml`.
### Пример
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress-coffee-minion
annotations:
angie.software/mergeable-ingress-type: "minion"
angie.software/path-regex: "case_sensitive"
spec:
ingressClassName: angie
rules:
- host: cafe.example.com
http:
paths:
- path: /coffee/[A-Za-z0-9]
pathType: Prefix
backend:
service:
name: coffee-svc
port:
number: 80
```
5. Примените изменения:
```console
kubectl apply -f coffee-minion.yaml
```
6. Проверьте, что изменения применились:
```console
kubectl describe ingress cafe-ingress-coffee-minion
Name: cafe-ingress-coffee-minion
Labels:
Namespace: default
Address:
Ingress Class: angie
Default backend:
Rules:
Host Path Backends
---- ---- --------
cafe.example.com
/coffee/[A-Za-z0-9] coffee-svc:80 (10.244.0.10:8080,10.244.0.9:8080)
Annotations: angie.software/mergeable-ingress-type: minion
angie.software/path-regex: case_sensitive
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal AddedOrUpdated 11m angie-ingress-controller Configuration for default/cafe-ingress-coffee-minion was added or updated
```
Добавленная аннотация `path-regex` обновляет путь `/coffee/[A-Za-z0-9]`, используя модификатор регулярного выражения `case_sensitive`.
Обновленный путь в конфигурационном файле Angie будет выглядеть так:
```nginx
location ~ "^/coffee/[A-Za-z0-9]"
```
# https://angie.software/anic/docs/custom-resources.md
# Примеры для пользовательских ресурсов
В этом разделе собраны примеры настройки и типовые конфигурации для пользовательских ресурсов.
[Базовая конфигурация](https://angie.software//anic/docs/custom-resources/basic-configuration.md#basic-configuration)
[Базовая аутентификация](https://angie.software//anic/docs/custom-resources/basic_authentication.md#basic-authentication)
[Базовая балансировка TCP- и UDP-трафика](https://angie.software//anic/docs/custom-resources/basic-tcp-udp.md#basic-tcp-udp)
[Контроль доступа](https://angie.software//anic/docs/custom-resources/access-control.md#access-control)
[Конфигурация для нескольких пространств имен](https://angie.software//anic/docs/custom-resources/cross-namespace-configuration.md#cross-namespace-configuration)
[Ограничение скорости запросов (rateLimit)](https://angie.software//anic/docs/custom-resources/rate-limit.md#rate-limit)
[Поддержка переписывания (rewrites)](https://angie.software//anic/docs/custom-resources/rewrites.md#rewrites)
[Распределение трафика](https://angie.software//anic/docs/custom-resources/traffic-splitting.md#traffic-splitting)
[Расширенная маршрутизация](https://angie.software//anic/docs/custom-resources/advanced-routing.md#advanced-routing)
[Сохранение сессий](https://angie.software//anic/docs/custom-resources/session-persistence.md#session-persistence)
[Cert-manager](https://angie.software//anic/docs/custom-resources/certmanager.md#certmanager)
[gRPC](https://angie.software//anic/docs/custom-resources/grpc-upstreams.md#grpc-upstreams)
[Ingress MTLS](https://angie.software//anic/docs/custom-resources/ingress-mtls.md#ingress-mtls)
[JWKS](https://angie.software//anic/docs/custom-resources/jwks.md#jwks)
[JWT](https://angie.software//anic/docs/custom-resources/jwt.md#jwt)
[OIDC](https://angie.software//anic/docs/custom-resources/configuring-oidc.md#configuring-oidc)
[TLS Passthrough](https://angie.software//anic/docs/custom-resources/tls-passthrough.md#tls-passthrough)
# https://angie.software/anic/docs/custom-resources/basic-configuration.md
# Базовая конфигурация
Ниже приведен пример настройки балансировки нагрузки с терминацией TLS для простого веб-приложения с использованием ресурса VirtualServer.
Приложение "cafe" позволяет получить `tea` через сервис `tea` или `coffee` через сервис `coffee`.
Выбор определяется URI HTTP-запроса: запросы с URI, оканчивающимися на `/tea`, возвращают `tea`, а с `/coffee` — `coffee`.
## Предварительные действия
1. Установите ANIC с включенной поддержкой пользовательских ресурсов.
2. Сохраните публичный IP-адрес ANIC в переменной оболочки:
```console
$ IC_IP=<ваш_IP-адрес>
```
3. Сохраните HTTPS-порт ANIC в переменной оболочки:
```console
$ IC_HTTPS_PORT=<номер порта>
```
## Настройка базовой конфигурации
1. Создайте Deployment и Service для `tea` и `coffee`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: coffee
spec:
replicas: 2
selector:
matchLabels:
app: coffee
template:
metadata:
labels:
app: coffee
spec:
containers:
- name: coffee
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: coffee-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: coffee
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: tea
spec:
replicas: 1
selector:
matchLabels:
app: tea
template:
metadata:
labels:
app: tea
spec:
containers:
- name: tea
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: tea-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: tea
```
Примените настройки:
```console
$ kubectl create -f cafe.yaml
```
2. Создайте секрет с TLS-сертификатом и ключом:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: cafe-secret
type: kubernetes.io/tls
data:
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURMakNDQWhZQ0NRREFPRjl0THNhWFdqQU5CZ2txaGtpRzl3MEJBUXNGQURCYU1Rc3dDUVlEVlFRR0V3SlYKVXpFTE1Ba0dBMVVFQ0F3Q1EwRXhJVEFmQmdOVkJBb01HRWx1ZEdWeWJtVjBJRmRwWkdkcGRITWdVSFI1SUV4MApaREViTUJrR0ExVUVBd3dTWTJGbVpTNWxlR0Z0Y0d4bExtTnZiU0FnTUI0WERURTRNRGt4TWpFMk1UVXpOVm9YCkRUSXpNRGt4TVRFMk1UVXpOVm93V0RFTE1Ba0dBMVVFQmhNQ1ZWTXhDekFKQmdOVkJBZ01Ba05CTVNFd0h3WUQKVlFRS0RCaEpiblJsY201bGRDQlhhV1JuYVhSeklGQjBlU0JNZEdReEdUQVhCZ05WQkFNTUVHTmhabVV1WlhoaApiWEJzWlM1amIyMHdnZ0VpTUEwR0NTcUdTSWIzRFFFQkFRVUFBNElCRHdBd2dnRUtBb0lCQVFDcDZLbjdzeTgxCnAwanVKL2N5ayt2Q0FtbHNmanRGTTJtdVpOSzBLdGVjcUcyZmpXUWI1NXhRMVlGQTJYT1N3SEFZdlNkd0kyaloKcnVXOHFYWENMMnJiNENaQ0Z4d3BWRUNyY3hkam0zdGVWaVJYVnNZSW1tSkhQUFN5UWdwaW9iczl4N0RsTGM2SQpCQTBaalVPeWwwUHFHOVNKZXhNVjczV0lJYTVyRFZTRjJyNGtTa2JBajREY2o3TFhlRmxWWEgySTVYd1hDcHRDCm42N0pDZzQyZitrOHdnemNSVnA4WFprWldaVmp3cTlSVUtEWG1GQjJZeU4xWEVXZFowZXdSdUtZVUpsc202OTIKc2tPcktRajB2a29QbjQxRUUvK1RhVkVwcUxUUm9VWTNyemc3RGtkemZkQml6Rk8yZHNQTkZ4MkNXMGpYa05MdgpLbzI1Q1pyT2hYQUhBZ01CQUFFd0RRWUpLb1pJaHZjTkFRRUxCUUFEZ2dFQkFLSEZDY3lPalp2b0hzd1VCTWRMClJkSEliMzgzcFdGeW5acS9MdVVvdnNWQTU4QjBDZzdCRWZ5NXZXVlZycTVSSWt2NGxaODFOMjl4MjFkMUpINnIKalNuUXgrRFhDTy9USkVWNWxTQ1VwSUd6RVVZYVVQZ1J5anNNL05VZENKOHVIVmhaSitTNkZBK0NuT0Q5cm4yaQpaQmVQQ0k1ckh3RVh3bm5sOHl3aWozdnZRNXpISXV5QmdsV3IvUXl1aTlmalBwd1dVdlVtNG52NVNNRzl6Q1Y3ClBwdXd2dWF0cWpPMTIwOEJqZkUvY1pISWc4SHc5bXZXOXg5QytJUU1JTURFN2IvZzZPY0s3TEdUTHdsRnh2QTgKN1dqRWVxdW5heUlwaE1oS1JYVmYxTjM0OWVOOThFejM4Zk9USFRQYmRKakZBL1BjQytHeW1lK2lHdDVPUWRGaAp5UkU9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBcWVpcCs3TXZOYWRJN2lmM01wUHJ3Z0pwYkg0N1JUTnBybVRTdENyWG5LaHRuNDFrCkcrZWNVTldCUU5semtzQndHTDBuY0NObzJhN2x2S2wxd2k5cTIrQW1RaGNjS1ZSQXEzTVhZNXQ3WGxZa1YxYkcKQ0pwaVJ6ejBza0lLWXFHN1BjZXc1UzNPaUFRTkdZMURzcGRENmh2VWlYc1RGZTkxaUNHdWF3MVVoZHErSkVwRwp3SStBM0kreTEzaFpWVng5aU9WOEZ3cWJRcCt1eVFvT05uL3BQTUlNM0VWYWZGMlpHVm1WWThLdlVWQ2cxNWhRCmRtTWpkVnhGbldkSHNFYmltRkNaYkp1dmRySkRxeWtJOUw1S0Q1K05SQlAvazJsUkthaTAwYUZHTjY4NE93NUgKYzMzUVlzeFR0bmJEelJjZGdsdEkxNURTN3lxTnVRbWF6b1Z3QndJREFRQUJBb0lCQVFDUFNkU1luUXRTUHlxbApGZlZGcFRPc29PWVJoZjhzSStpYkZ4SU91UmF1V2VoaEp4ZG01Uk9ScEF6bUNMeUw1VmhqdEptZTIyM2dMcncyCk45OUVqVUtiL1ZPbVp1RHNCYzZvQ0Y2UU5SNThkejhjbk9SVGV3Y290c0pSMXBuMWhobG5SNUhxSkpCSmFzazEKWkVuVVFmY1hackw5NGxvOUpIM0UrVXFqbzFGRnM4eHhFOHdvUEJxalpzVjdwUlVaZ0MzTGh4bndMU0V4eUZvNApjeGI5U09HNU9tQUpvelN0Rm9RMkdKT2VzOHJKNXFmZHZ5dGdnOXhiTGFRTC94MGtwUTYyQm9GTUJEZHFPZVBXCktmUDV6WjYvMDcvdnBqNDh5QTFRMzJQem9idWJzQkxkM0tjbjMyamZtMUU3cHJ0V2wrSmVPRmlPem5CUUZKYk4KNHFQVlJ6NWhBb0dCQU50V3l4aE5DU0x1NFArWGdLeWNrbGpKNkY1NjY4Zk5qNUN6Z0ZScUowOXpuMFRsc05ybwpGVExaY3hEcW5SM0hQWU00MkpFUmgySi9xREZaeW5SUW8zY2czb2VpdlVkQlZHWTgrRkkxVzBxZHViL0w5K3l1CmVkT1pUUTVYbUdHcDZyNmpleHltY0ppbS9Pc0IzWm5ZT3BPcmxEN1NQbUJ2ek5MazRNRjZneGJYQW9HQkFNWk8KMHA2SGJCbWNQMHRqRlhmY0tFNzdJbUxtMHNBRzR1SG9VeDBlUGovMnFyblRuT0JCTkU0TXZnRHVUSnp5K2NhVQprOFJxbWRIQ2JIelRlNmZ6WXEvOWl0OHNaNzdLVk4xcWtiSWN1YytSVHhBOW5OaDFUanNSbmU3NFowajFGQ0xrCmhIY3FIMHJpN1BZU0tIVEU4RnZGQ3haWWRidUI4NENtWmlodnhicFJBb0dBSWJqcWFNWVBUWXVrbENkYTVTNzkKWVNGSjFKelplMUtqYS8vdER3MXpGY2dWQ0thMzFqQXdjaXowZi9sU1JxM0hTMUdHR21lemhQVlRpcUxmZVpxYwpSMGlLYmhnYk9jVlZrSkozSzB5QXlLd1BUdW14S0haNnpJbVpTMGMwYW0rUlk5WUdxNVQ3WXJ6cHpjZnZwaU9VCmZmZTNSeUZUN2NmQ21mb09oREN0enVrQ2dZQjMwb0xDMVJMRk9ycW40M3ZDUzUxemM1em9ZNDR1QnpzcHd3WU4KVHd2UC9FeFdNZjNWSnJEakJDSCtULzZzeXNlUGJKRUltbHpNK0l3eXRGcEFOZmlJWEV0LzQ4WGY2ME54OGdXTQp1SHl4Wlp4L05LdER3MFY4dlgxUE9ucTJBNWVpS2ErOGpSQVJZS0pMWU5kZkR1d29seHZHNmJaaGtQaS80RXRUCjNZMThzUUtCZ0h0S2JrKzdsTkpWZXN3WEU1Y1VHNkVEVXNEZS8yVWE3ZlhwN0ZjanFCRW9hcDFMU3crNlRYcDAKWmdybUtFOEFSek00NytFSkhVdmlpcS9udXBFMTVnMGtKVzNzeWhwVTl6WkxPN2x0QjBLSWtPOVpSY21Vam84UQpjcExsSE1BcWJMSjhXWUdKQ2toaVd4eWFsNmhZVHlXWTRjVmtDMHh0VGwvaFVFOUllTktvCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==
```
Примените настройки:
```console
$ kubectl create -f cafe-secret.yaml
```
3. Создайте ресурс VirtualServer:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: cafe
spec:
host: cafe.example.com
tls:
secret: cafe-secret
upstreams:
- name: tea
service: tea-svc
port: 80
- name: coffee
service: coffee-svc
port: 80
routes:
- path: /tea
action:
pass: tea
- path: /coffee
action:
pass: coffee
```
Примените настройки:
```console
$ kubectl create -f cafe-virtual-server.yaml
```
4. Протестируйте конфигурацию.
Проверьте, что конфигурация успешно применена, посмотрев события ресурса VirtualServer:
```console
$ kubectl describe virtualserver cafe
```
Ожидаемый результат:
```console
...
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal AddedOrUpdated 7s ANIC Configuration for default/cafe was added or updated
```
5. Получите доступ к приложению с помощью `curl`.
Используйте опцию `--insecure`, чтобы отключить проверку сертификата, и `--resolve`, чтобы задать IP-адрес и порт Ingress-контроллера для домена `cafe.example.com`.
Чтобы получить `coffee`:
```console
$ curl --resolve cafe.example.com:$IC_HTTPS_PORT:$IC_IP \
https://cafe.example.com:$IC_HTTPS_PORT/coffee --insecure
```
Ожидаемый результат:
```console
Server address: 10.16.1.182:80
Server name: coffee-7dbb5795f6-tnbtq
...
```
Чтобы получить `tea`:
```console
$ curl --resolve cafe.example.com:$IC_HTTPS_PORT:$IC_IP \
https://cafe.example.com:$IC_HTTPS_PORT/tea --insecure
```
Ожидаемый результат:
```console
Server address: 10.16.0.149:80
Server name: tea-7d57856c44-zlftd
...
```
# https://angie.software/anic/docs/custom-resources/basic_authentication.md
# Настройка базовой аутентификации
ANIC поддерживает аутентификацию запросов с использованием модуля [Auth Basic](https://angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic).
Ниже приведен пример развертывания веб-приложения, настройки балансировщика для ресурса VirtualServer
и применения политики базовой аутентификации.
## Предварительные действия
1. Установите ANIC.
2. Сохраните публичный IP-адрес ANIC в переменной оболочки:
```console
$ IC_IP=<ваш_IP-адрес>
```
3. Сохраните HTTP-порт ANIC в переменную оболочки:
```console
$ IC_HTTP_PORT=<номер порта>
```
## Настройка базовой аутентификации
1. Создайте Deployment и Service для приложения:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: coffee
spec:
replicas: 2
selector:
matchLabels:
app: coffee
template:
metadata:
labels:
app: coffee
spec:
containers:
- name: coffee
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: coffee-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: coffee
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: tea
spec:
replicas: 1
selector:
matchLabels:
app: tea
template:
metadata:
labels:
app: tea
spec:
containers:
- name: tea
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: tea-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: tea
```
Примените настройки:
```console
$ kubectl apply -f cafe.yaml
```
2. Создайте секрет типа `angie.software/htpasswd` с именем `cafe-passwd`, который будет использоваться
для базовой аутентификации. Секрет должен содержать список пар `user:password` в формате Base64:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: cafe-secret
type: kubernetes.io/tls
data:
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURMakNDQWhZQ0NRREFPRjl0THNhWFdqQU5CZ2txaGtpRzl3MEJBUXNGQURCYU1Rc3dDUVlEVlFRR0V3SlYKVXpFTE1Ba0dBMVVFQ0F3Q1EwRXhJVEFmQmdOVkJBb01HRWx1ZEdWeWJtVjBJRmRwWkdkcGRITWdVSFI1SUV4MApaREViTUJrR0ExVUVBd3dTWTJGbVpTNWxlR0Z0Y0d4bExtTnZiU0FnTUI0WERURTRNRGt4TWpFMk1UVXpOVm9YCkRUSXpNRGt4TVRFMk1UVXpOVm93V0RFTE1Ba0dBMVVFQmhNQ1ZWTXhDekFKQmdOVkJBZ01Ba05CTVNFd0h3WUQKVlFRS0RCaEpiblJsY201bGRDQlhhV1JuYVhSeklGQjBlU0JNZEdReEdUQVhCZ05WQkFNTUVHTmhabVV1WlhoaApiWEJzWlM1amIyMHdnZ0VpTUEwR0NTcUdTSWIzRFFFQkFRVUFBNElCRHdBd2dnRUtBb0lCQVFDcDZLbjdzeTgxCnAwanVKL2N5ayt2Q0FtbHNmanRGTTJtdVpOSzBLdGVjcUcyZmpXUWI1NXhRMVlGQTJYT1N3SEFZdlNkd0kyaloKcnVXOHFYWENMMnJiNENaQ0Z4d3BWRUNyY3hkam0zdGVWaVJYVnNZSW1tSkhQUFN5UWdwaW9iczl4N0RsTGM2SQpCQTBaalVPeWwwUHFHOVNKZXhNVjczV0lJYTVyRFZTRjJyNGtTa2JBajREY2o3TFhlRmxWWEgySTVYd1hDcHRDCm42N0pDZzQyZitrOHdnemNSVnA4WFprWldaVmp3cTlSVUtEWG1GQjJZeU4xWEVXZFowZXdSdUtZVUpsc202OTIKc2tPcktRajB2a29QbjQxRUUvK1RhVkVwcUxUUm9VWTNyemc3RGtkemZkQml6Rk8yZHNQTkZ4MkNXMGpYa05MdgpLbzI1Q1pyT2hYQUhBZ01CQUFFd0RRWUpLb1pJaHZjTkFRRUxCUUFEZ2dFQkFLSEZDY3lPalp2b0hzd1VCTWRMClJkSEliMzgzcFdGeW5acS9MdVVvdnNWQTU4QjBDZzdCRWZ5NXZXVlZycTVSSWt2NGxaODFOMjl4MjFkMUpINnIKalNuUXgrRFhDTy9USkVWNWxTQ1VwSUd6RVVZYVVQZ1J5anNNL05VZENKOHVIVmhaSitTNkZBK0NuT0Q5cm4yaQpaQmVQQ0k1ckh3RVh3bm5sOHl3aWozdnZRNXpISXV5QmdsV3IvUXl1aTlmalBwd1dVdlVtNG52NVNNRzl6Q1Y3ClBwdXd2dWF0cWpPMTIwOEJqZkUvY1pISWc4SHc5bXZXOXg5QytJUU1JTURFN2IvZzZPY0s3TEdUTHdsRnh2QTgKN1dqRWVxdW5heUlwaE1oS1JYVmYxTjM0OWVOOThFejM4Zk9USFRQYmRKakZBL1BjQytHeW1lK2lHdDVPUWRGaAp5UkU9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBcWVpcCs3TXZOYWRJN2lmM01wUHJ3Z0pwYkg0N1JUTnBybVRTdENyWG5LaHRuNDFrCkcrZWNVTldCUU5semtzQndHTDBuY0NObzJhN2x2S2wxd2k5cTIrQW1RaGNjS1ZSQXEzTVhZNXQ3WGxZa1YxYkcKQ0pwaVJ6ejBza0lLWXFHN1BjZXc1UzNPaUFRTkdZMURzcGRENmh2VWlYc1RGZTkxaUNHdWF3MVVoZHErSkVwRwp3SStBM0kreTEzaFpWVng5aU9WOEZ3cWJRcCt1eVFvT05uL3BQTUlNM0VWYWZGMlpHVm1WWThLdlVWQ2cxNWhRCmRtTWpkVnhGbldkSHNFYmltRkNaYkp1dmRySkRxeWtJOUw1S0Q1K05SQlAvazJsUkthaTAwYUZHTjY4NE93NUgKYzMzUVlzeFR0bmJEelJjZGdsdEkxNURTN3lxTnVRbWF6b1Z3QndJREFRQUJBb0lCQVFDUFNkU1luUXRTUHlxbApGZlZGcFRPc29PWVJoZjhzSStpYkZ4SU91UmF1V2VoaEp4ZG01Uk9ScEF6bUNMeUw1VmhqdEptZTIyM2dMcncyCk45OUVqVUtiL1ZPbVp1RHNCYzZvQ0Y2UU5SNThkejhjbk9SVGV3Y290c0pSMXBuMWhobG5SNUhxSkpCSmFzazEKWkVuVVFmY1hackw5NGxvOUpIM0UrVXFqbzFGRnM4eHhFOHdvUEJxalpzVjdwUlVaZ0MzTGh4bndMU0V4eUZvNApjeGI5U09HNU9tQUpvelN0Rm9RMkdKT2VzOHJKNXFmZHZ5dGdnOXhiTGFRTC94MGtwUTYyQm9GTUJEZHFPZVBXCktmUDV6WjYvMDcvdnBqNDh5QTFRMzJQem9idWJzQkxkM0tjbjMyamZtMUU3cHJ0V2wrSmVPRmlPem5CUUZKYk4KNHFQVlJ6NWhBb0dCQU50V3l4aE5DU0x1NFArWGdLeWNrbGpKNkY1NjY4Zk5qNUN6Z0ZScUowOXpuMFRsc05ybwpGVExaY3hEcW5SM0hQWU00MkpFUmgySi9xREZaeW5SUW8zY2czb2VpdlVkQlZHWTgrRkkxVzBxZHViL0w5K3l1CmVkT1pUUTVYbUdHcDZyNmpleHltY0ppbS9Pc0IzWm5ZT3BPcmxEN1NQbUJ2ek5MazRNRjZneGJYQW9HQkFNWk8KMHA2SGJCbWNQMHRqRlhmY0tFNzdJbUxtMHNBRzR1SG9VeDBlUGovMnFyblRuT0JCTkU0TXZnRHVUSnp5K2NhVQprOFJxbWRIQ2JIelRlNmZ6WXEvOWl0OHNaNzdLVk4xcWtiSWN1YytSVHhBOW5OaDFUanNSbmU3NFowajFGQ0xrCmhIY3FIMHJpN1BZU0tIVEU4RnZGQ3haWWRidUI4NENtWmlodnhicFJBb0dBSWJqcWFNWVBUWXVrbENkYTVTNzkKWVNGSjFKelplMUtqYS8vdER3MXpGY2dWQ0thMzFqQXdjaXowZi9sU1JxM0hTMUdHR21lemhQVlRpcUxmZVpxYwpSMGlLYmhnYk9jVlZrSkozSzB5QXlLd1BUdW14S0haNnpJbVpTMGMwYW0rUlk5WUdxNVQ3WXJ6cHpjZnZwaU9VCmZmZTNSeUZUN2NmQ21mb09oREN0enVrQ2dZQjMwb0xDMVJMRk9ycW40M3ZDUzUxemM1em9ZNDR1QnpzcHd3WU4KVHd2UC9FeFdNZjNWSnJEakJDSCtULzZzeXNlUGJKRUltbHpNK0l3eXRGcEFOZmlJWEV0LzQ4WGY2ME54OGdXTQp1SHl4Wlp4L05LdER3MFY4dlgxUE9ucTJBNWVpS2ErOGpSQVJZS0pMWU5kZkR1d29seHZHNmJaaGtQaS80RXRUCjNZMThzUUtCZ0h0S2JrKzdsTkpWZXN3WEU1Y1VHNkVEVXNEZS8yVWE3ZlhwN0ZjanFCRW9hcDFMU3crNlRYcDAKWmdybUtFOEFSek00NytFSkhVdmlpcS9udXBFMTVnMGtKVzNzeWhwVTl6WkxPN2x0QjBLSWtPOVpSY21Vam84UQpjcExsSE1BcWJMSjhXWUdKQ2toaVd4eWFsNmhZVHlXWTRjVmtDMHh0VGwvaFVFOUllTktvCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==
```
```yaml
kind: Secret
metadata:
name: cafe-passwd
apiVersion: v1
type: angie.software/htpasswd
stringData:
htpasswd: |
foo:$2y$10$e4CiBWaLq9JW93jV8r9CW.RE6fbsT3szmIsUhwqYuPfVlggXiBY76
qux:$apr1$st218vzc$A3H7I83N9vLmczj73Byi3/
# bar
# quux
```
Примените настройки:
```console
$ kubectl apply -f cafe-passwd.yaml
```
3. Создайте политику `basic-auth-policy`, которая ссылается на секрет
из предыдущего шага и разрешает запросы к веб-приложению только при наличии
действительной пары `user:password`.
```yaml
apiVersion: k8s.angie.software/v1
kind: Policy
metadata:
name: basic-auth-policy
spec:
basicAuth:
realm: Cafe App
secret: cafe-passwd
```
Примените настройки:
```console
$ kubectl apply -f basic-auth-policy.yaml
```
4. Создайте ресурс VirtualServer для веб-приложения:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: cafe
spec:
host: cafe.example.com
policies:
- name: basic-auth-policy
upstreams:
- name: tea
service: tea-svc
port: 80
- name: coffee
service: coffee-svc
port: 80
routes:
- path: /tea
action:
pass: tea
- path: /coffee
action:
pass: coffee
```
Примените настройки:
```console
$ kubectl apply -f cafe-virtual-server.yaml
```
Обратите внимание, что VirtualServer должен ссылаться на политику `basic-auth-policy`, созданную на шаге 3.
5. Протестируйте конфигурацию.
Если вы укажете неверные данные авторизации, ANIC отклонит запрос для указанного ресурса VirtualServer при попытке обратиться к приложению:
```console
$ curl --resolve cafe.example.com:$IC_HTTP_PORT:$IC_IP http://cafe.example.com:$IC_HTTP_PORT/
401 Authorization Required
401 Authorization Required
Angie/1.8.1
```
Если вы укажете действительные данные, запрос будет выполнен:
```console
$ curl --resolve cafe.example.com:$IC_HTTPS_PORT:$IC_IP https://cafe.example.com:$IC_HTTPS_PORT/coffee --insecure -u foo:bar
Server address: 10.244.0.6:8080
Server name: coffee-7b9b4bbd99-bdbxm
Date: 20/Jun/2024:11:43:34 +0000
URI: /coffee
Request ID: f91f15d1af17556e552557df2f5a0dd2
```
# https://angie.software/anic/docs/custom-resources/basic-tcp-udp.md
# Базовая балансировка TCP- и UDP-трафика
Ниже приведен пример развертывания DNS-сервера в кластере и настройки балансировки TCP- и UDP-трафика для него с использованием ресурса `TransportServer`. ANIC будет передавать все соединения или датаграммы, поступающие на порт 5353, в поды DNS-сервера.
## Предварительные действия
1. Установите ANIC:
- Убедитесь, что ресурс `GlobalConfiguration` развернут и ANIC использует его.
- Откройте порт 5353 как для TCP-, так и для UDP-трафика.
2. Сохраните публичный IP-адрес ANIC в переменной оболочки:
```console
$ IC_IP=<ваш_IP-адрес>
```
3. Сохраните порт 5353, используемый ANIC, в переменной оболочки:
```console
$ IC_5353_PORT=<номер порта>
```
#### NOTE
Если вы хотите настроить ANIC с помощью сервиса `LoadBalancer`, то в нем нельзя использовать
протоколы TCP и UDP одновременно.
В этом случае создайте два отдельных сервиса: для TCP и для UDP.
Соответственно, у вас будет два разных публичных IP-адреса (см. примеры на последнем шаге).
4. Убедитесь, что у вас установлена утилита `dig` (используется для тестирования).
#### NOTE
В процессе установки ANIC ресурс `GlobalConfiguration` должен
быть развернут в пространстве имен `angie-ingress` с именем `angie-configuration`.
Если это не так, обновите файл `global-configuration.yaml`, правильно указав пространство имен и имя.
## Балансировка TCP/UDP-трафика
1. Разверните DNS-сервер:
- Разверните две реплики `CoreDNS`, настроенные на пересылку DNS-запросов на `8.8.8.8`.
- Создайте сервис `coredns`, который откроет порт 5353 как для TCP, так и для UDP.
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: coredns
data:
Corefile: |
.:5353 {
forward . 8.8.8.8:53
log
}
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: coredns
spec:
replicas: 2
selector:
matchLabels:
app: coredns
template:
metadata:
labels:
app: coredns
spec:
containers:
- name: coredns
image: coredns/coredns:1.10.0
args: [ "-conf", "/etc/coredns/Corefile" ]
volumeMounts:
- name: config-volume
mountPath: /etc/coredns
readOnly: true
ports:
- containerPort: 5353
name: dns
protocol: UDP
- containerPort: 5353
name: dns-tcp
protocol: TCP
securityContext:
readOnlyRootFilesystem: true
volumes:
- name: config-volume
configMap:
name: coredns
items:
- key: Corefile
path: Corefile
---
apiVersion: v1
kind: Service
metadata:
name: coredns
spec:
selector:
app: coredns
ports:
- name: dns
port: 5353
protocol: UDP
- name: dns-tcp
port: 5353
protocol: TCP
```
Примените настройки:
```console
$ kubectl apply -f dns.yaml
```
2. Настройте слушатели.
Обновите ресурс `GlobalConfiguration`, добавив два слушателя: один для TCP-порта 5353 и один для UDP-порта 5353:
```yaml
apiVersion: k8s.angie.software/v1alpha1
kind: GlobalConfiguration
metadata:
name: angie-configuration
namespace: angie-ingress
spec:
listeners:
- name: dns-udp
port: 5353
protocol: UDP
- name: dns-tcp
port: 5353
protocol: TCP
```
Примените настройки:
```console
$ kubectl apply -f global-configuration.yaml
```
3. Проверьте, что конфигурация успешно применена, просмотрев события `GlobalConfiguration`:
```console
$ kubectl describe gc angie-configuration -n angie-ingress
```
Пример вывода:
```console
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Updated 0s (x2 over 10s) anic GlobalConfiguration anic/angie-configuration was updated
```
4. Настройте балансировку нагрузки.
Создайте ресурс `TransportServer`, чтобы настроить балансировку TCP:
```yaml
apiVersion: k8s.angie.software/v1alpha1
kind: TransportServer
metadata:
name: dns-tcp
spec:
listener:
name: dns-tcp
protocol: TCP
upstreams:
- name: dns-app
service: coredns
port: 5353
action:
pass: dns-app
```
Примените настройки:
```console
$ kubectl apply -f transport-server-tcp.yaml
```
5. Проверьте, что конфигурация успешно применена:
```console
$ kubectl describe ts dns-tcp
```
Пример вывода:
```console
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal AddedOrUpdated 3s anic Configuration for default/dns-tcp was added or updated
```
6. Создайте ресурс `TransportServer`, чтобы настроить балансировку UDP:
```yaml
apiVersion: k8s.angie.software/v1alpha1
kind: TransportServer
metadata:
name: dns-udp
spec:
listener:
name: dns-udp
protocol: UDP
upstreams:
- name: dns-app
service: coredns
port: 5353
upstreamParameters:
udpRequests: 1
udpResponses: 1
action:
pass: dns-app
```
Примените настройки:
```console
$ kubectl apply -f transport-server-udp.yaml
```
7. Проверьте, что конфигурация успешно применена:
```console
$ kubectl describe ts dns-udp
```
Пример вывода:
```console
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal AddedOrUpdated 0s anic Configuration for default/dns-udp was added or updated
```
8. Протестируйте конфигурацию.
Чтобы проверить, что настроенный балансировщик нагрузки TCP/UDP работает, разрешите DNS-имя `kubernetes.io` с помощью DNS-сервера.
Разрешение `kubernetes.io` через TCP:
```shell
$ dig @$IC_IP -p $IC_5353_PORT kubernetes.io +tcp
; <<>> DiG 9.10.3-P4-Debian <<>> @ -p 5353 kubernetes.io +tcp
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 44784
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
;; QUESTION SECTION:
;kubernetes.io. IN A
;; ANSWER SECTION:
kubernetes.io. 3596 IN A 147.75.40.148
;; Query time: 134 msec
;; SERVER: #5353()
;; WHEN: Thu Mar 12 22:01:55 UTC 2020
;; MSG SIZE rcvd: 71
```
Разрешение `kubernetes.io` через UDP:
```shell
$ dig @$IC_IP -p $IC_5353_PORT kubernetes.io
; <<>> DiG 9.10.3-P4-Debian <<>> @ -p 5353 kubernetes.io
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 39087
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
;; QUESTION SECTION:
;kubernetes.io. IN A
;; ANSWER SECTION:
kubernetes.io. 2157 IN A 147.75.40.148
;; Query time: 134 msec
;; SERVER: #5353()
;; WHEN: Thu Mar 12 22:02:12 UTC 2020
;; MSG SIZE rcvd: 71
```
# https://angie.software/anic/docs/custom-resources/access-control.md
# Контроль доступа
Ниже приведен пример развертывания веб-приложения, настройки балансировки нагрузки с помощью VirtualServer и применения политики управления доступом для запрета и разрешения трафика из определенной подсети.
## Предварительные действия
1. Установите ANIC.
2. Сохраните публичный IP-адрес ANIC в переменной оболочки:
```console
$ IC_IP=<ваш_IP-адрес>
```
3. Сохраните HTTP-порт ANIC в переменной оболочки:
```console
$ IC_HTTP_PORT=<номер порта>
```
## Настройка контроля доступа
1. Создайте Deployment и Service для приложения:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: webapp
spec:
selector:
matchLabels:
app: webapp
template:
metadata:
labels:
app: webapp
spec:
containers:
- name: webapp
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: webapp-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: webapp
```
Примените настройки:
```console
$ kubectl apply -f webapp.yaml
```
2. Создайте политику `webapp-policy`, которая запрещает запросы от клиентов с IP-адресами из подсети `10.0.0.0/8`.
Убедитесь, что поле `deny` в файле `access-control-policy-deny.yaml` настроено
в соответствии с вашей средой:
```yaml
apiVersion: k8s.angie.software/v1
kind: Policy
metadata:
name: webapp-policy
spec:
accessControl:
deny:
- 10.0.0.0/8
```
Примените настройки:
```console
$ kubectl apply -f access-control-policy-deny.yaml
```
3. Создайте ресурс VirtualServer для веб-приложения:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: webapp
spec:
host: webapp.example.com
policies:
- name: webapp-policy
upstreams:
- name: webapp
service: webapp-svc
port: 80
routes:
- path: /
action:
pass: webapp
```
Примените настройки:
```console
$ kubectl apply -f virtual-server.yaml
```
Обратите внимание, что VirtualServer должен ссылаться на политику `webapp-policy`, созданную на шаге 2.
4. Протестируйте конфигурацию.
Попробуйте обратиться к приложению:
```console
$ curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT
```
Ожидаемый результат:
```html
403 Forbidden
403 Forbidden
Angie/1.8.1
```
Ответ `403 Forbidden` означает успешное срабатывание политики блокировки запросов.
5. Обновите политику, чтобы разрешить запросы от клиентов из подсети `10.0.0.0/8`.
Убедитесь, что поле `allow` в файле `access-control-policy-allow.yaml` настроено в соответствии с вашей средой:
```console
apiVersion: k8s.angie.software/v1
kind: Policy
metadata:
name: webapp-policy
spec:
accessControl:
allow:
- 10.0.0.0/8
```
Обновите политику:
```console
$ kubectl apply -f access-control-policy-allow.yaml
```
6. Повторно протестируйте конфигурацию.
Попробуйте обратиться к приложению:
```console
$ curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT
```
Ожидаемый результат:
```console
Server address: 10.64.0.13:8080
Server name: webapp-5cbbc7bd78-wf85w
```
Ответ `200 OK` означает успешное разрешение запроса после обновления политики.
# https://angie.software/anic/docs/custom-resources/cross-namespace-configuration.md
# Конфигурация для нескольких пространств имен
Ниже приведен пример использования ресурсов VirtualServer и VirtualServerRoute при настройке балансировки нагрузки
для модифицированного приложения "cafe" из примера базовой конфигурации.
Конфигурация балансировки нагрузки, а также Deployments и Services размещены в нескольких пространствах имен.
Вместо одного пространства имен теперь используются три: `tea`, `coffee` и `cafe`:
- В пространстве имен `tea` созданы Deployment, Service и соответствующая конфигурация балансировки нагрузки.
- В пространстве имен `coffee` созданы Deployment, Service и соответствующая конфигурация балансировки нагрузки.
- В пространстве имен `cafe` создан секрет с TLS-сертификатом и ключом,
а также конфигурация балансировки нагрузки для приложения "cafe".
Эта конфигурация ссылается на конфигурации `coffee` и `tea`.
## Предварительные действия
1. Установите ANIC с включенными пользовательскими ресурсами.
2. Сохраните публичный IP-адрес ANIC в переменной оболочки:
```console
$ IC_IP=<ваш_IP-адрес>
```
3. Сохраните HTTPS-порт ANIC в переменной оболочки:
```console
$ IC_HTTPS_PORT=<номер порта>
```
## Настройка конфигурации для нескольких пространств имен
1. Создайте необходимые пространства имен `tea`, `coffee` и `cafe`:
```yaml
apiVersion: v1
kind: Namespace
metadata:
name: cafe
---
apiVersion: v1
kind: Namespace
metadata:
name: tea
---
apiVersion: v1
kind: Namespace
metadata:
name: coffee
```
Примените настройки:
```console
$ kubectl create -f namespaces.yaml
```
2. Создайте Deployment и Service для `tea` в пространстве имен `tea`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: tea
namespace: tea
spec:
replicas: 1
selector:
matchLabels:
app: tea
template:
metadata:
labels:
app: tea
spec:
containers:
- name: tea
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: tea-svc
namespace: tea
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: tea
```
Примените настройки:
```console
$ kubectl create -f tea.yaml
```
3. Создайте Deployment и Service для `coffee` в пространстве имен `coffee`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: coffee
namespace: coffee
spec:
replicas: 1
selector:
matchLabels:
app: coffee
template:
metadata:
labels:
app: coffee
spec:
containers:
- name: coffee
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: coffee-svc
namespace: coffee
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: coffee
```
Примените настройки:
```console
$ kubectl create -f coffee.yaml
```
4. Создайте ресурс VirtualServerRoute для `tea` в пространстве имен `tea`:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServerRoute
metadata:
name: tea
namespace: tea
spec:
host: cafe.example.com
upstreams:
- name: tea
service: tea-svc
port: 80
subroutes:
- path: /tea
action:
pass: tea
```
Примените настройки:
```console
$ kubectl create -f tea-virtual-server-route.yaml
```
5. Создайте ресурс VirtualServerRoute для `coffee` в пространстве имен `coffee`:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServerRoute
metadata:
name: coffee
namespace: coffee
spec:
host: cafe.example.com
upstreams:
- name: coffee
service: coffee-svc
port: 80
subroutes:
- path: /coffee
action:
pass: coffee
```
Примените настройки:
```console
$ kubectl create -f coffee-virtual-server-route.yaml
```
6. Создайте секрет с TLS-сертификатом и ключом в пространстве имен `cafe`:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: cafe-secret
namespace: cafe
type: kubernetes.io/tls
data:
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURMakNDQWhZQ0NRREFPRjl0THNhWFdqQU5CZ2txaGtpRzl3MEJBUXNGQURCYU1Rc3dDUVlEVlFRR0V3SlYKVXpFTE1Ba0dBMVVFQ0F3Q1EwRXhJVEFmQmdOVkJBb01HRWx1ZEdWeWJtVjBJRmRwWkdkcGRITWdVSFI1SUV4MApaREViTUJrR0ExVUVBd3dTWTJGbVpTNWxlR0Z0Y0d4bExtTnZiU0FnTUI0WERURTRNRGt4TWpFMk1UVXpOVm9YCkRUSXpNRGt4TVRFMk1UVXpOVm93V0RFTE1Ba0dBMVVFQmhNQ1ZWTXhDekFKQmdOVkJBZ01Ba05CTVNFd0h3WUQKVlFRS0RCaEpiblJsY201bGRDQlhhV1JuYVhSeklGQjBlU0JNZEdReEdUQVhCZ05WQkFNTUVHTmhabVV1WlhoaApiWEJzWlM1amIyMHdnZ0VpTUEwR0NTcUdTSWIzRFFFQkFRVUFBNElCRHdBd2dnRUtBb0lCQVFDcDZLbjdzeTgxCnAwanVKL2N5ayt2Q0FtbHNmanRGTTJtdVpOSzBLdGVjcUcyZmpXUWI1NXhRMVlGQTJYT1N3SEFZdlNkd0kyaloKcnVXOHFYWENMMnJiNENaQ0Z4d3BWRUNyY3hkam0zdGVWaVJYVnNZSW1tSkhQUFN5UWdwaW9iczl4N0RsTGM2SQpCQTBaalVPeWwwUHFHOVNKZXhNVjczV0lJYTVyRFZTRjJyNGtTa2JBajREY2o3TFhlRmxWWEgySTVYd1hDcHRDCm42N0pDZzQyZitrOHdnemNSVnA4WFprWldaVmp3cTlSVUtEWG1GQjJZeU4xWEVXZFowZXdSdUtZVUpsc202OTIKc2tPcktRajB2a29QbjQxRUUvK1RhVkVwcUxUUm9VWTNyemc3RGtkemZkQml6Rk8yZHNQTkZ4MkNXMGpYa05MdgpLbzI1Q1pyT2hYQUhBZ01CQUFFd0RRWUpLb1pJaHZjTkFRRUxCUUFEZ2dFQkFLSEZDY3lPalp2b0hzd1VCTWRMClJkSEliMzgzcFdGeW5acS9MdVVvdnNWQTU4QjBDZzdCRWZ5NXZXVlZycTVSSWt2NGxaODFOMjl4MjFkMUpINnIKalNuUXgrRFhDTy9USkVWNWxTQ1VwSUd6RVVZYVVQZ1J5anNNL05VZENKOHVIVmhaSitTNkZBK0NuT0Q5cm4yaQpaQmVQQ0k1ckh3RVh3bm5sOHl3aWozdnZRNXpISXV5QmdsV3IvUXl1aTlmalBwd1dVdlVtNG52NVNNRzl6Q1Y3ClBwdXd2dWF0cWpPMTIwOEJqZkUvY1pISWc4SHc5bXZXOXg5QytJUU1JTURFN2IvZzZPY0s3TEdUTHdsRnh2QTgKN1dqRWVxdW5heUlwaE1oS1JYVmYxTjM0OWVOOThFejM4Zk9USFRQYmRKakZBL1BjQytHeW1lK2lHdDVPUWRGaAp5UkU9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBcWVpcCs3TXZOYWRJN2lmM01wUHJ3Z0pwYkg0N1JUTnBybVRTdENyWG5LaHRuNDFrCkcrZWNVTldCUU5semtzQndHTDBuY0NObzJhN2x2S2wxd2k5cTIrQW1RaGNjS1ZSQXEzTVhZNXQ3WGxZa1YxYkcKQ0pwaVJ6ejBza0lLWXFHN1BjZXc1UzNPaUFRTkdZMURzcGRENmh2VWlYc1RGZTkxaUNHdWF3MVVoZHErSkVwRwp3SStBM0kreTEzaFpWVng5aU9WOEZ3cWJRcCt1eVFvT05uL3BQTUlNM0VWYWZGMlpHVm1WWThLdlVWQ2cxNWhRCmRtTWpkVnhGbldkSHNFYmltRkNaYkp1dmRySkRxeWtJOUw1S0Q1K05SQlAvazJsUkthaTAwYUZHTjY4NE93NUgKYzMzUVlzeFR0bmJEelJjZGdsdEkxNURTN3lxTnVRbWF6b1Z3QndJREFRQUJBb0lCQVFDUFNkU1luUXRTUHlxbApGZlZGcFRPc29PWVJoZjhzSStpYkZ4SU91UmF1V2VoaEp4ZG01Uk9ScEF6bUNMeUw1VmhqdEptZTIyM2dMcncyCk45OUVqVUtiL1ZPbVp1RHNCYzZvQ0Y2UU5SNThkejhjbk9SVGV3Y290c0pSMXBuMWhobG5SNUhxSkpCSmFzazEKWkVuVVFmY1hackw5NGxvOUpIM0UrVXFqbzFGRnM4eHhFOHdvUEJxalpzVjdwUlVaZ0MzTGh4bndMU0V4eUZvNApjeGI5U09HNU9tQUpvelN0Rm9RMkdKT2VzOHJKNXFmZHZ5dGdnOXhiTGFRTC94MGtwUTYyQm9GTUJEZHFPZVBXCktmUDV6WjYvMDcvdnBqNDh5QTFRMzJQem9idWJzQkxkM0tjbjMyamZtMUU3cHJ0V2wrSmVPRmlPem5CUUZKYk4KNHFQVlJ6NWhBb0dCQU50V3l4aE5DU0x1NFArWGdLeWNrbGpKNkY1NjY4Zk5qNUN6Z0ZScUowOXpuMFRsc05ybwpGVExaY3hEcW5SM0hQWU00MkpFUmgySi9xREZaeW5SUW8zY2czb2VpdlVkQlZHWTgrRkkxVzBxZHViL0w5K3l1CmVkT1pUUTVYbUdHcDZyNmpleHltY0ppbS9Pc0IzWm5ZT3BPcmxEN1NQbUJ2ek5MazRNRjZneGJYQW9HQkFNWk8KMHA2SGJCbWNQMHRqRlhmY0tFNzdJbUxtMHNBRzR1SG9VeDBlUGovMnFyblRuT0JCTkU0TXZnRHVUSnp5K2NhVQprOFJxbWRIQ2JIelRlNmZ6WXEvOWl0OHNaNzdLVk4xcWtiSWN1YytSVHhBOW5OaDFUanNSbmU3NFowajFGQ0xrCmhIY3FIMHJpN1BZU0tIVEU4RnZGQ3haWWRidUI4NENtWmlodnhicFJBb0dBSWJqcWFNWVBUWXVrbENkYTVTNzkKWVNGSjFKelplMUtqYS8vdER3MXpGY2dWQ0thMzFqQXdjaXowZi9sU1JxM0hTMUdHR21lemhQVlRpcUxmZVpxYwpSMGlLYmhnYk9jVlZrSkozSzB5QXlLd1BUdW14S0haNnpJbVpTMGMwYW0rUlk5WUdxNVQ3WXJ6cHpjZnZwaU9VCmZmZTNSeUZUN2NmQ21mb09oREN0enVrQ2dZQjMwb0xDMVJMRk9ycW40M3ZDUzUxemM1em9ZNDR1QnpzcHd3WU4KVHd2UC9FeFdNZjNWSnJEakJDSCtULzZzeXNlUGJKRUltbHpNK0l3eXRGcEFOZmlJWEV0LzQ4WGY2ME54OGdXTQp1SHl4Wlp4L05LdER3MFY4dlgxUE9ucTJBNWVpS2ErOGpSQVJZS0pMWU5kZkR1d29seHZHNmJaaGtQaS80RXRUCjNZMThzUUtCZ0h0S2JrKzdsTkpWZXN3WEU1Y1VHNkVEVXNEZS8yVWE3ZlhwN0ZjanFCRW9hcDFMU3crNlRYcDAKWmdybUtFOEFSek00NytFSkhVdmlpcS9udXBFMTVnMGtKVzNzeWhwVTl6WkxPN2x0QjBLSWtPOVpSY21Vam84UQpjcExsSE1BcWJMSjhXWUdKQ2toaVd4eWFsNmhZVHlXWTRjVmtDMHh0VGwvaFVFOUllTktvCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==
```
Примените настройки:
```console
$ kubectl create -f cafe-secret.yaml
```
7. Создайте ресурс VirtualServer для приложения "cafe" в пространстве имен `cafe`:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: cafe
namespace: cafe
spec:
host: cafe.example.com
tls:
secret: cafe-secret
routes:
- path: /tea
route: tea/tea
- path: /coffee
route: coffee/coffee
```
Примените настройки:
```console
$ kubectl create -f cafe-virtual-server.yaml
```
8. Протестируйте конфигурацию.
Проверьте, что конфигурация была успешно применена, просмотрев события ресурсов VirtualServerRoute и VirtualServer:
```console
$ kubectl describe virtualserverroute tea -n tea
```
Вывод:
```console
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning NoVirtualServersFound 2m ANIC No VirtualServer references VirtualServerRoute tea/tea
Normal AddedOrUpdated 1m ANIC Configuration for tea/tea was added or updated
```
```console
$ kubectl describe virtualserverroute coffee -n coffee
```
Вывод:
```console
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning NoVirtualServersFound 2m ANIC No VirtualServer references VirtualServerRoute coffee/coffee
Normal AddedOrUpdated 1m ANIC Configuration for coffee/coffee was added or updated
```
```console
$ kubectl describe virtualserver cafe -n cafe
```
Вывод:
```console
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal AddedOrUpdated 1m ANIC Configuration for cafe/cafe was added or updated
```
9. Используйте `curl` для доступа к приложению. Опция `--insecure` отключает проверку сертификата,
так как используется самоподписанный сертификат. Опция `--resolve` позволяет
установить IP-адрес и HTTPS-порт Ingress-контроллера для доменного имени приложения "cafe".
Чтобы получить `coffee`:
```console
$ curl --resolve cafe.example.com:$IC_HTTPS_PORT:$IC_IP https://cafe.example.com:$IC_HTTPS_PORT/coffee --insecure
```
Ожидаемый результат:
```console
Server address: 10.16.1.193:80
Server name: coffee-7dbb5795f6-mltpf
...
```
Чтобы получить `tea`:
```console
$ curl --resolve cafe.example.com:$IC_HTTPS_PORT:$IC_IP https://cafe.example.com:$IC_HTTPS_PORT/tea --insecure
```
Ожидаемый результат:
```console
Server address: 10.16.0.157:80
Server name: tea-7d57856c44-674b8
...
```
# https://angie.software/anic/docs/custom-resources/rate-limit.md
# Ограничение скорости запросов
В этом примере развертывается веб-приложение, настраивается балансировка нагрузки с помощью VirtualServer и применяется политика ограничения скорости запросов.
## Предварительные действия
1. Установите ANIC.
2. Сохраните публичный IP-адрес ANIC в переменной оболочки:
```console
$ IC_IP=<ваш_IP-адрес>
```
3. Сохраните HTTP-порт ANIC в переменной оболочки:
```console
$ IC_HTTP_PORT=<номер порта>
```
## Развертывание веб-приложения
1. Создайте Deployment и Service для приложения:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: webapp
spec:
replicas: 1
selector:
matchLabels:
app: webapp
template:
metadata:
labels:
app: webapp
spec:
containers:
- name: webapp
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: webapp-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: webapp
```
Примените настройки:
```console
$ kubectl apply -f webapp.yaml
```
2. Создайте политику с именем `rate-limit-policy`, которая разрешает только один запрос в секунду с одного IP-адреса.
```yaml
apiVersion: k8s.angie.software/v1
kind: Policy
metadata:
name: rate-limit-policy
spec:
rateLimit:
rate: 1r/s
key: ${binary_remote_addr}
zoneSize: 10M
```
Примените настройки:
```console
$ kubectl apply -f rate-limit.yaml
```
3. Создайте ресурс VirtualServer для веб-приложения:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: webapp
spec:
host: webapp.example.com
policies:
- name: rate-limit-policy
upstreams:
- name: webapp
service: webapp-svc
port: 80
routes:
- path: /
action:
pass: webapp
```
Примените настройки:
```console
$ kubectl apply -f virtual-server.yaml
```
VirtualServer ссылается на политику `rate-limit-policy`, созданную выше.
4. Протестируйте конфигурацию.
Если вы будете запрашивать приложение с частотой выше одного запроса в секунду, ANIC начнет отклонять ваши запросы:
```console
$ curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT/
Server address: 10.8.1.19:8080
Server name: webapp-dc88fc766-zr7f8
...
```
```console
$ curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT/
503 Service Temporarily Unavailable
503 Service Temporarily Unavailable
Angie/1.8.1
```
#### NOTE
Вывод команды сокращен для наглядности примера.
# https://angie.software/anic/docs/custom-resources/rewrites.md
# Поддержка переписывания (rewrites)
ANIC позволяет преобразовывать (переписывать) URI запроса перед отправкой в приложение.
Например, путь запроса `/tea/green` может быть перезаписан как `/green`.
Для настройки изменения URI необходимо использовать `ActionProxy`
в `VirtualServer` или `VirtualServerRoute`.
## Пример с префиксом в пути
В следующем примере нагрузка между двумя приложениями, требующими изменения URI,
балансируется с помощью префиксного сопоставления:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: cafe
spec:
host: cafe.example.com
upstreams:
- name: tea
service: tea-svc
port: 80
- name: coffee
service: coffee-svc
port: 80
routes:
- path: /tea/
action:
proxy:
upstream: tea
rewritePath: /
- path: /coffee
action:
proxy:
upstream: coffee
rewritePath: /beans
```
Изменения URI для `tea-svc` (обратите внимание,
что запросы к `/tea` перенаправляются на `/tea/` с добавлением косой черты в конце):
| Исходный URI | Переписанный URI |
|----------------|--------------------|
| `/tea/` | `/` |
| `/tea/abc` | `/abc` |
Изменения URI для `coffee-svc`:
| Исходный URI | Переписанный URI |
|----------------|--------------------|
| `/coffee` | `/beans` |
| `/coffee/` | `/beans/` |
| `/coffee/abc` | `/beans/abc` |
## Пример с регулярными выражениями
Если путь представляет собой регулярное выражение, а не префикс или точное соответствие,
`rewritePath` может содержать группы захвата `$1-9`.
Пример:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: cafe
spec:
host: cafe.example.com
upstreams:
- name: tea
service: tea-svc
port: 80
routes:
- path: ~ /tea/?(.*)
action:
proxy:
upstream: tea
rewritePath: /$1
```
В этом примере группа захвата `(.*)` используется в `rewritePath` как `/$1`.
Это необходимо для передачи оставшейся части URI запроса (после `/tea`).
Примеры изменения URI для `tea-svc`:
| Исходный URI | Переписанный URI |
|----------------|--------------------|
| `/tea` | `/` |
| `/tea/` | `/` |
| `/tea/abc` | `/abc` |
# https://angie.software/anic/docs/custom-resources/traffic-splitting.md
# Распределение трафика
Ниже приведен пример использования ресурса `VirtualServer` для настройки распределения трафика в приложении `Cafe`.
Относительно базовой конфигурации были внесены следующие изменения:
- Вместо одной версии сервиса `coffee` теперь есть две: `coffee-v1-svc` и `coffee-v2-svc`.
- 90% трафика направляется на `coffee-v1-svc`, а оставшиеся 10% — на `coffee-v2-svc`.
- Для упрощения примера убраны TLS-терминация и сервис `tea`.
## Предварительные действия
1. Установите ANIC с включенными пользовательскими ресурсами.
2. Сохраните публичный IP-адрес ANIC в переменной оболочки:
```console
$ IC_IP=<ваш_IP-адрес>
```
3. Сохраните HTTP-порт ANIC в переменной оболочки:
```console
$ IC_HTTP_PORT=<номер порта>
```
## Настройка распределения трафика
1. Создайте Deployment и Service для `coffee`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: coffee-v1
spec:
replicas: 2
selector:
matchLabels:
app: coffee-v1
template:
metadata:
labels:
app: coffee-v1
spec:
containers:
- name: coffee-v1
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: coffee-v1-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: coffee-v1
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: coffee-v2
spec:
replicas: 2
selector:
matchLabels:
app: coffee-v2
template:
metadata:
labels:
app: coffee-v2
spec:
containers:
- name: coffee-v2
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: coffee-v2-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: coffee-v2
```
Примените настройки:
```console
$ kubectl create -f cafe.yaml
```
2. Настройте балансировку нагрузки.
Создайте ресурс `VirtualServer`:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: cafe
spec:
host: cafe.example.com
upstreams:
- name: coffee-v1
service: coffee-v1-svc
port: 80
- name: coffee-v2
service: coffee-v2-svc
port: 80
routes:
- path: /coffee
splits:
- weight: 90
action:
pass: coffee-v1
- weight: 10
action:
pass: coffee-v2
```
Примените настройки:
```console
$ kubectl create -f cafe-virtual-server.yaml
```
3. Проверьте, что конфигурация успешно применена, просмотрев события `VirtualServer`:
```console
$ kubectl describe virtualserver cafe
```
Пример вывода:
```console
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal AddedOrUpdated 5s anic Configuration for default/cafe was added or updated
```
4. Проверьте работу приложения с помощью `curl`.
Используйте `--resolve`, чтобы указать IP-адрес и HTTP-порт ANIC для домена `cafe.example.com`.
Выполните несколько запросов, чтобы убедиться, что ANIC направляет трафик на разные версии сервиса `coffee`:
```console
$ curl --resolve cafe.example.com:$IC_HTTP_PORT:$IC_IP http://cafe.example.com:$IC_HTTP_PORT/coffee
```
Результат:
- 90% запросов будут направлены на `coffee-v1-svc`:
```console
Server address: 10.16.0.151:80
Server name: coffee-v1-78754bdcfb-7xp27
...
```
- 10% запросов будут направлены на `coffee-v2-svc`:
```console
Server address: 10.16.0.152:80
Server name: coffee-v2-7fd446968b-lwhgcd
...
```
# https://angie.software/anic/docs/custom-resources/advanced-routing.md
# Расширенная маршрутизация
Ниже приведен пример настройки расширенной маршрутизации с помощью ресурса VirtualServer для приложения "cafe" из примера настройки базовой конфигурации.
Внесены следующие изменения:
- Вместо одной версии сервиса `tea` теперь две: `tea-post-svc` и `tea-svc`.
POST-запросы для `tea` направляются в `tea-post-svc`.
Остальные запросы (например, GET) направляются в `tea-svc`.
- Вместо одной версии сервиса `coffee` теперь две: `coffee-v1-svc` и `coffee-v2-svc`.
Запросы, содержащие cookie `version=v2`, направляются в `coffee-v2-svc`.
Все остальные запросы направляются в `coffee-v1-svc`.
- Для упрощения из примера удалена поддержка TLS.
## Предварительные действия
1. Установите ANIC с включенными пользовательскими ресурсами.
2. Сохраните публичный IP-адрес ANIC в переменной оболочки:
```console
$ IC_IP=<ваш_IP-адрес>
```
3. Сохраните HTTP-порт ANIC в переменной оболочки:
```console
$ IC_HTTP_PORT=<номер порта>
```
## Настройка расширенной маршрутизации
1. Создайте Deployment и Service для `coffee` и `tea`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: coffee-v1
spec:
replicas: 1
selector:
matchLabels:
app: coffee-v1
template:
metadata:
labels:
app: coffee-v1
spec:
containers:
- name: coffee-v1
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: coffee-v1-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: coffee-v1
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: coffee-v2
spec:
replicas: 1
selector:
matchLabels:
app: coffee-v2
template:
metadata:
labels:
app: coffee-v2
spec:
containers:
- name: coffee-v2
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: coffee-v2-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: coffee-v2
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: tea-post
spec:
replicas: 1
selector:
matchLabels:
app: tea-post
template:
metadata:
labels:
app: tea-post
spec:
containers:
- name: tea-post
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: tea-post-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: tea-post
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: tea
spec:
replicas: 1
selector:
matchLabels:
app: tea
template:
metadata:
labels:
app: tea
spec:
containers:
- name: tea
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: tea-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: tea
```
Примените настройки:
```console
$ kubectl create -f cafe.yaml
```
2. Создайте ресурс VirtualServer:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: cafe
spec:
host: cafe.example.com
upstreams:
- name: tea-post
service: tea-post-svc
port: 80
- name: tea
service: tea-svc
port: 80
- name: coffee-v1
service: coffee-v1-svc
port: 80
- name: coffee-v2
service: coffee-v2-svc
port: 80
routes:
- path: /tea
authRequest: /auth/path
authRequestSets:
- key: foo
value: bar
matches:
- conditions:
- variable: $request_method
value: POST
action:
pass: tea-post
action:
pass: tea-post
- path: /coffee
matches:
- conditions:
- cookie: version
value: v2
action:
pass: coffee-v2
action:
pass: coffee-v1
authRequestLocations:
- path: /auth/path
proxyPass:
upstreamName: "tea"
proxyPassHeaders:
- key: Content-Length
value: "100"
```
Примените настройки:
```console
$ kubectl create -f cafe-virtual-server.yaml
```
3. Протестируйте конфигурацию.
Проверьте, что конфигурация была успешно применена, просмотрев события ресурса VirtualServer:
```console
$ kubectl describe virtualserver cafe
```
Вывод:
```console
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal AddedOrUpdated 2s ANIC Configuration for default/cafe was added or updated
```
4. Протестируйте доступ к сервису `tea`.
Отправьте POST-запрос и убедитесь, что ответ приходит от `tea-post-svc`:
```console
$ curl --resolve cafe.example.com:$IC_HTTP_PORT:$IC_IP http://cafe.example.com:$IC_HTTP_PORT/tea -X POST
```
Ожидаемый результат:
```console
Server address: 10.16.1.188:80
Server name: tea-post-b5dd479b4-6ssmh
. . .
```
Отправьте GET-запрос и убедитесь, что ответ приходит от `tea-svc`:
```console
$ curl --resolve cafe.example.com:$IC_HTTP_PORT:$IC_IP http://cafe.example.com:$IC_HTTP_PORT/tea
```
Ожидаемый результат:
```console
Server address: 10.16.1.189:80
Server name: tea-7d57856c44-2hsvr
. . .
```
5. Протестируйте доступ к сервису `coffee`.
Отправьте запрос с cookie `version=v2` и убедитесь, что ответ приходит от `coffee-v2-svc`:
```console
$ curl --resolve cafe.example.com:$IC_HTTP_PORT:$IC_IP http://cafe.example.com:$IC_HTTP_PORT/coffee --cookie "version=v2"
```
Ожидаемый результат:
```console
Server address: 10.16.1.187:80
Server name: coffee-v2-7fd446968b-vkthp
. . .
```
Отправьте запрос без cookie и убедитесь, что ответ приходит от `coffee-v1-svc`:
```console
$ curl --resolve cafe.example.com:$IC_HTTP_PORT:$IC_IP http://cafe.example.com:$IC_HTTP_PORT/coffee
```
Ожидаемый результат:
```console
Server address: 10.16.0.153:80
Server name: coffee-v1-78754bdcfb-bs9nh
. . .
```
# https://angie.software/anic/docs/custom-resources/session-persistence.md
# Сохранение сессий
Часто необходимо, чтобы запросы от клиента всегда передавались одному и тому же контейнеру бэкенда.
Вы можете включить такое поведение с помощью функции сохранения сессий, доступной в ANIC.
ANIC поддерживает метод `sticky cookie`.
При использовании этого метода ANIC добавляет session cookie в первый ответ от бэкенда,
идентифицируя контейнер, который отправил ответ.
Когда клиент делает следующий запрос, он отправляет значение `cookie`,
и ANIC направляет запрос в тот же контейнер.
## Синтаксис
Чтобы включить сохранение сессий для одного или нескольких сервисов,
нужно настроить блок `sessionCookie` в конфигурации апстрима для каждого сервиса.
В аннотации указываются сервисы, для которых нужно включить сохранение сессий,
а также различные параметры `cookie`. См. директиву [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) в конфигурации Angie.
## Пример
В следующем примере мы включаем сохранение сессий для двух сервисов:
`tea-svc` и `coffee-svc`:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: cafe
spec:
host: cafe.example.com
tls:
secret: cafe-secret
upstreams:
- name: tea
service: tea-svc
port: 80
sessionCookie:
enable: true
name: srv_id
path: /tea
expires: 2h
- name: coffee
service: coffee-svc
port: 80
sessionCookie:
enable: true
name: srv_id
path: /coffee
expires: 1h
routes:
- path: /tea
action:
pass: tea
- path: /coffee
action:
pass: coffee
```
Для обоих сервисов sticky cookie имеет одинаковое имя `srv_id`.
Однако для каждого сервиса заданы разные значения времени жизни (`expires`) и пути (`path`).
Сохранение сессий продолжает работать даже в случае,
если запущено несколько реплик ANIC.
# https://angie.software/anic/docs/custom-resources/certmanager.md
# Cert-manager
Ниже приведены примеры:
- развертывания `cert-manager` и самоподписанного центра сертификации;
- развертывания ANIC;
- развертывания простого веб-приложения;
- настройки балансировки нагрузки для этого приложения с помощью ресурса `VirtualServer`.
## Развертывание cert-manager и самоподписанного центра сертификации
1. Разверните `cert-manager` и все необходимые зависимости:
```console
$ kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.8.0/cert-manager.yaml
```
2. Разверните `Issuer` (самоподписанный центр сертификации):
```yaml
apiVersion: v1
kind: Namespace
metadata:
name: sandbox
---
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: selfsigned-issuer
spec:
selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: my-selfsigned-ca
namespace: sandbox
spec:
isCA: true
commonName: my-selfsigned-ca
secretName: root-secret
privateKey:
algorithm: ECDSA
size: 256
issuerRef:
name: selfsigned-issuer
kind: ClusterIssuer
group: cert-manager.io
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: my-ca-issuer
namespace: sandbox
spec:
ca:
secretName: root-secret
```
Примените настройки:
```console
$ kubectl apply -f self-signed.yaml
```
## Запуск примера
1. Установите ANIC. Включите поддержку `cert-manager` для ресурсов `VirtualServer`:
```console
--enable-custom-resources --enable-cert-manager
```
2. Сохраните публичный IP-адрес ANIC в переменной оболочки:
```console
$ IC_IP=<ваш_IP-адрес>
```
3. Сохраните HTTPS-порт ANIC в переменной оболочки:
```console
$ IC_HTTPS_PORT=<номер порта>
```
4. Создайте Deployment и Service для `coffee` и `tea`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: coffee
spec:
replicas: 2
selector:
matchLabels:
app: coffee
template:
metadata:
labels:
app: coffee
spec:
containers:
- name: coffee
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: coffee-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: coffee
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: tea
spec:
replicas: 3
selector:
matchLabels:
app: tea
template:
metadata:
labels:
app: tea
spec:
containers:
- name: tea
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: tea-svc
labels:
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: tea
```
Примените настройки:
```console
$ kubectl create -f cafe.yaml
```
5. Создайте ресурс `VirtualServer`:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: cafe
spec:
host: cafe.example.com
tls:
secret: cafe-secret
cert-manager:
cluster-issuer: selfsigned-issuer
upstreams:
- name: tea
service: tea-svc
port: 80
- name: coffee
service: coffee-svc
port: 80
routes:
- path: /tea
action:
pass: tea
- path: /coffee
action:
pass: coffee
```
Примените настройки:
```console
$ kubectl create -f cafe-virtual-server.yaml
```
6. Протестируйте приложение.
Используйте `curl` для проверки сервисов `coffee` и `tea`:
`--insecure`, чтобы отключить проверку сертификата, и `--resolve`,
чтобы указать заголовок `Host` в запросе с `cafe.example.com`.
Запрос к сервису `coffee`:
```console
$ curl --resolve cafe.example.com:$IC_HTTPS_PORT:$IC_IP https://cafe.example.com:$IC_HTTPS_PORT/coffee --insecure
```
Пример ответа:
```console
Server address: 10.12.0.18:80
Server name: coffee-7586895968-r26zn
...
```
Запрос к сервису `tea`:
```console
$ curl --resolve cafe.example.com:$IC_HTTPS_PORT:$IC_IP https://cafe.example.com:$IC_HTTPS_PORT/tea --insecure
```
Пример ответа:
```console
Server address: 10.12.0.19:80
Server name: tea-7cd44fcb4d-xfw2x
...
```
# https://angie.software/anic/docs/custom-resources/grpc-upstreams.md
# gRPC
Для поддержки gRPC-приложений с помощью ресурсов `VirtualServer` необходимо добавить поле `type: grpc` в `upstream`.
Если этот параметр не указан, по умолчанию будет использован протокол `http`.
## Предварительная настройка
- Необходимо включить прослушиватель `HTTP/2`. См. `http2` в [ConfigMap](https://angie.software//anic/docs/configuration/configmap-resource.md#configmap-resource).
- Ресурсы `VirtualServer` и `VirtualServerRoute` для gRPC-приложений должны включать терминацию TLS.
## Пример
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: grpc-vs
spec:
host: grpc.example.com
tls:
secret: grpc-secret
upstreams:
- name: grpc1
service: grpc-svc
port: 50051
type: grpc
routes:
- path: /helloworld.Greeter
action:
pass: grpc1
```
В этом примере `grpc-svc` — это сервис для gRPC-приложения. Он будет доступен по пути `/helloworld.Greeter`.
Обратите внимание, что в конфигурации `upstream` используется поле `type: grpc`.
# https://angie.software/anic/docs/custom-resources/ingress-mtls.md
# Ingress MTLS
Ниже приведен пример развертывания веб-приложения, настройки балансировки нагрузки с помощью VirtualServer и применения политики Ingress MTLS.
#### NOTE
Политика Ingress MTLS поддерживает настройку списка аннулированных сертификатов (CRL).
Подробности см. [Использование списка отзыва сертификатов](https://angie.software//anic/docs/configuration/policy-resource.md#cert-revocation).
## Предварительные действия
1. Установите ANIC.
2. Сохраните публичный IP-адрес ANIC в переменной оболочки:
```console
$ IC_IP=<ваш_IP-адрес>
```
3. Сохраните HTTPS-порт ANIC в переменной оболочки:
```console
$ IC_HTTPS_PORT=<номер порта>
```
## Настройка Ingress MTLS
1. Создайте Deployment и Service для приложения:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: webapp
spec:
replicas: 1
selector:
matchLabels:
app: webapp
template:
metadata:
labels:
app: webapp
spec:
containers:
- name: webapp
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: webapp-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: webapp
```
Примените настройки:
```console
$ kubectl apply -f webapp.yaml
```
2. Создайте секрет с именем `ingress-mtls-secret`, который будет использоваться для валидации Ingress MTLS:
```yaml
kind: Secret
metadata:
name: ingress-mtls-secret
apiVersion: v1
type: angie.software/ca
data:
ca.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUQvVENDQXVXZ0F3SUJBZ0lVSzdhbU14OFlLWG1BVG51SkZETDlWS2ZUR2ZNd0RRWUpLb1pJaHZjTkFRRUwKQlFBd2dZMHhDekFKQmdOVkJBWVRBbFZUTVFzd0NRWURWUVFJREFKRFFURVdNQlFHQTFVRUJ3d05VMkZ1SUVaeQpZVzVqYVhOamJ6RU9NQXdHQTFVRUNnd0ZUa2RKVGxneEREQUtCZ05WQkFzTUEwdEpRekVXTUJRR0ExVUVBd3dOCmEybGpMbTVuYVc1NExtTnZiVEVqTUNFR0NTcUdTSWIzRFFFSkFSWVVhM1ZpWlhKdVpYUmxjMEJ1WjJsdWVDNWoKYjIwd0hoY05NakF3T1RFNE1qQXlOVEkyV2hjTk16QXdPVEUyTWpBeU5USTJXakNCalRFTE1Ba0dBMVVFQmhNQwpWVk14Q3pBSkJnTlZCQWdNQWtOQk1SWXdGQVlEVlFRSERBMVRZVzRnUm5KaGJtTnBjMk52TVE0d0RBWURWUVFLCkRBVk9SMGxPV0RFTU1Bb0dBMVVFQ3d3RFMwbERNUll3RkFZRFZRUUREQTFyYVdNdWJtZHBibmd1WTI5dE1TTXcKSVFZSktvWklodmNOQVFrQkZoUnJkV0psY201bGRHVnpRRzVuYVc1NExtTnZiVENDQVNJd0RRWUpLb1pJaHZjTgpBUUVCQlFBRGdnRVBBRENDQVFvQ2dnRUJBTmFINVRzaTZzaUFsU085dEJnYmY3VVRwcWowMUhRTlQ2UjhtQy9pCjhLYXFaSW9XSUdvN2xhTW9xTDYydTc4ay9WOHM2Z0FJaU1DSzBjekFvTFhNSnlJQkxQeTg4Yzdtc2xwZXgxTkEKVmRtMkVTVkN6bVlERE1TT3FpVmszWmpYeC9URmo2QzhNRFhhRkZUWFg1dWdtbWdscnFCWlh0OVI5VVBwVTJMNwo1bEZ0NlJ2R3VGczgvbVZORVR5c1A0SFhCWlh2ZE9mdG1YWUkvK01hOW5CMzIzNjdmcTI0L0RKZ2YvK2xRbUsxCkJLR3poSTZSc1pSSmdWOXdpK1VuZTBYNjlaS2lLOFdXU3lZS252YnRrcHZuTDA2dGNJaXJZNi80UzZ4Sm1HRVQKZEJUNmVxc0NoSUpQUStWSEp5dTROdnV6WmVCUXpGdmMwNytnUGZkVWZra1FXODhDQXdFQUFhTlRNRkV3SFFZRApWUjBPQkJZRUZKUGdhcnFYa00rdEJ0djVhdndTUWhUQmpTU2VNQjhHQTFVZEl3UVlNQmFBRkpQZ2FycVhrTSt0CkJ0djVhdndTUWhUQmpTU2VNQThHQTFVZEV3RUIvd1FGTUFNQkFmOHdEUVlKS29aSWh2Y05BUUVMQlFBRGdnRUIKQUl3WXpoY0s4OWtRL0xGWjZFRHgrQWp2bnJTVSs1cmdwQkgrRjVTNUUyY3pXOE5rNXhySnl0Y0ZUbUtlKzZScwpENHlxeTZSVVFEeWNYaDlPelBjbzgzYTBoeFlCZ1M5MWtJa25wYWF4dndLRDJleWc3UGNnK1lkS1FhZFlMcUY0CmI3cWVtc1FVVkpOWHdkZS9VanRBejlEOTh4dngwM2hQY2Qwb2dzUUhWZ21BZVpFd2l3UzFmTy9WNUE4dTl3MEkKcHlJRTVReXlHcHNpS2dpalpiMmhrS05RVHVJcEhiVnFydVA4eEV6TlFnamhkdS9uUW5OYy9lRUltVUlrQkFUVQpiSHdQc2xwYzVhdVV1TXJxR3lEQ0p2QUJpV3J2SmE3Yi9XcmtDT3FUWVhtR2NGM0w1ZU9FeTBhYkp0M2NNcSs5CnJLTUNVQWlkNG0yNEthWnc3OUk2anNBPQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
```
Примените настройки:
```console
$ kubectl apply -f ingress-mtls-secret.yaml
```
3. Создайте политику с именем `ingress-mtls-policy`, которая ссылается на секрет из предыдущего шага:
```yaml
apiVersion: k8s.angie.software/v1
kind: Policy
metadata:
name: ingress-mtls-policy
spec:
ingressMTLS:
clientCertSecret: ingress-mtls-secret
verifyClient: "on"
verifyDepth: 1
```
Примените настройки:
```console
$ kubectl apply -f ingress-mtls.yaml
```
4. Создайте секрет с TLS-сертификатом и ключом:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: tls-secret
type: kubernetes.io/tls
data:
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURHekNDQWdPZ0F3SUJBZ0lVWU90ZXQ1cnpjd2pFMlo1QUQzQS9tdVJFVzRRd0RRWUpLb1pJaHZjTkFRRUwKQlFBd0hURWJNQmtHQTFVRUF3d1NkMlZpWVhCd0xtVjRZVzF3YkdVdVkyOXRNQjRYRFRJd01Ea3lPVEl5TVRrMQpPVm9YRFRNd01Ea3lOekl5TVRrMU9Wb3dIVEViTUJrR0ExVUVBd3dTZDJWaVlYQndMbVY0WVcxd2JHVXVZMjl0Ck1JSUJJakFOQmdrcWhraUc5dzBCQVFFRkFBT0NBUThBTUlJQkNnS0NBUUVBeU5odlg5emoraGZvN0V2TzBsNlkKNzNUTGdMZEUzWWRGcURRT1RrL3JuajhzeWRPSUdrQ0IxR0VDcHAxcmc3bk9wTWVUNHovRlNsbzQ1TzJKWWRUNQplMC9YVWRkUk9JYytoS0V3NzNoejZjc2Fjd25NdjZzZWE2UDBSY1ZDQU1pdkZoeG9sWGRDUnlsZVdrVXczd29KClFRZFozNEZCQlFoVjFvMThHeGViWWFCTjF3bjMxdXZ4ZUxqMjVyQThKOUZjWElTQzJvMGpIZmZkSTFJamJjUHUKVlhJZkh0NFVMcHpnZlpQUVVnYzUrL3BkYVVRL0JHdkdiQ3o0cnBVbzhCQnQ2N0U5RlVoVE8vYnZnU1ljQ1A4dQpvTU9uY2hyNjZMSzJ3WE82ZWQyVHR4VmQySGJZRW5TRjFFZGRqZDdRQjJMUVoxUDJBbERBZll3YmZ3R3VMVGNhCjh3SURBUUFCbzFNd1VUQWRCZ05WSFE0RUZnUVVLOXlpL0tRQXp6SjRCcHdESndGTWF1cDJCREF3SHdZRFZSMGoKQkJnd0ZvQVVLOXlpL0tRQXp6SjRCcHdESndGTWF1cDJCREF3RHdZRFZSMFRBUUgvQkFVd0F3RUIvekFOQmdrcQpoa2lHOXcwQkFRc0ZBQU9DQVFFQWVuSFIybDJVNWdNQTMyek9YY2dDeTE0RXU3S2p3ayswRzFWbkNxU1IrMmhyCjdUSHVBVDRUSGpGYzFDWDQ4YXBiLzdwV3lJVlZoZ2IybXFMSDZTZlRWOEJtMEdLZUkyUU9VSVpZb2ZJeHZMeEMKRjRzd3FLVFc1SmgyUWJ2M3owN2hvTmpSZmR0WG1GS0pUWUZzS05WN3oyMVo4WWlFQ1o4NVMwRHpoU3BaSnk3MwpkdEV5NXlsVUZvb0JyeklzajFxRHlVZ2Zlck84TkZ3b2RlNDg4QThNMVNQNWZOOTBmSHZHRU9qRzdubG1IZDJJCkdvYkd2Z0kvT3l3RWVPMVFzdEFWckVtZVRvU0ZudStxZ09iUEpxRVFETExRS21SNkRNNzI5bkw4RXRIekZwTlkKZFcxeThRdkZxVm0yN1ZVdk8ybEduM0JUUmt0dWxSckJ3Sm9hQmF3TSt3PT0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=
tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUV2UUlCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktjd2dnU2pBZ0VBQW9JQkFRREkyRzlmM09QNkYranMKUzg3U1hwanZkTXVBdDBUZGgwV29OQTVPVCt1ZVB5ekowNGdhUUlIVVlRS21uV3VEdWM2a3g1UGpQOFZLV2pqawo3WWxoMVBsN1Q5ZFIxMUU0aHo2RW9URHZlSFBweXhwekNjeS9xeDVyby9SRnhVSUF5SzhXSEdpVmQwSkhLVjVhClJURGZDZ2xCQjFuZmdVRUZDRlhXalh3YkY1dGhvRTNYQ2ZmVzYvRjR1UGJtc0R3bjBWeGNoSUxhalNNZDk5MGoKVWlOdHcrNVZjaDhlM2hRdW5PQjlrOUJTQnpuNytsMXBSRDhFYThac0xQaXVsU2p3RUczcnNUMFZTRk03OXUrQgpKaHdJL3k2Z3c2ZHlHdnJvc3JiQmM3cDUzWk8zRlYzWWR0Z1NkSVhVUjEyTjN0QUhZdEJuVS9ZQ1VNQjlqQnQvCkFhNHROeHJ6QWdNQkFBRUNnZ0VBZTJ5V05PRDNzRzhWRW5FYnJpZTM4QjlrRjd1SU5HSzJxY0Vqc1hobm9SM04KbGxISjUrZ1FZTVVrN2VMN2VUMnNBWk1zREpEWjJ2RksyVlFvQXRqd1g1a1hCeEk4dFhKWE53WWZubW4xUVkwdwp1ZFVoMy85MmVFdVBCM2xMTUZRalZJRXN1LzFIMjVkT2hrYlMyNTI5UmhzUVhjdCtlMnM5NU5XWm1NU1BGaFJuCnJMeFFpSzFiTWJxcHVHRlUzSXYwd3ZVd2dQdjFUQkhYSzAzOFZ0WGtMLzFpVVNLWVBJOHQ3QmUrUTI0cklsVXkKK01BQ3pPdWpabWduWXFpYUJ5ZFNJeDJRM3VtUTFyL2hOMG5FbkNMdnNRSVZiVlhpTFZvQkpzenJCMEgyREI2cQphR096WHlGeG1HQ2JkbWpCaTlwb1FybEtmR2JwdWpIYnJmNmU0MWRZVVFLQmdRRHlueXBxdmFZaExSTXMwZTVFClhHcStIZ2lLZnlWbnNYd2RMUWF3ajRHTkF1WEtpaXBvNU5nb3IyNFN4NGIzejNuZ1QxalprbE40VlpxcUNFQmYKMno4S2o4VWREVS9BRzZwaDhITSszUEtUWXNOcElWdi9SbSs4cktPbU9uSGZJaWpGNDdvU0dyT3RVWnVyY2xXZQpjMkZuaHhiTHdISnZHYzd2VDV6VDlNTFMvd0tCZ1FEVDY0N0Q1ZFpDTllQcytLNU9Ub1JFNFJIdlpMSUdUWHRwClZEa2Vjdis3aUxoNis3aTFHRjZuMTZ2cEJrSXRmOXUvRk9SRVpoM1lpQk5Fcy93bGl6NHRVNDhrbDQrRVNjYlcKdUh2ZVY1NktBUHI2UGM3ajBJK1lMSXdoTURqMXVPSnV2eW9iSFJZQlJPajVGd3YvUk81ME9LdytLdXpwV2s4QQoxY1FYakVHY0RRS0JnRTRUam5EZkt2RU9NbGVBRHk4TWxvVXI0US9BcnViWnBOazJ2aXBmWkE5ZTJWZitjbnRpCitYVE9UNXZYZmNXTmpPajBYK0ZVUjJ3NEVCZWJwQ3Uwd0dyRHJXa1YrWTRXMlJPL2J6YlJuM1p5bC9QaStsb0IKN3I5R3h6c2RIN3Z3b0RKZWdHaUhFejg1UGVGRVgrMG5zRGJDc0VGTll3WUJ4aWdZOUp6NDdTRTlBb0dCQUozZgpzM2kvSlpJbmVnTzA4MjNFMG9iWndWbTlnMTVzcEk3QVB0a3ZSTks1dE8xeHo1V2g5UXBIQW52VHZNTldxQ2MrCjhocitsQ2Qyb0J3amxhbUdoU2lSUW1jNVBhS0lyOGZRb2Y3dStWM0lBekVma0p4cENFQ09sMG8yT1lqZFZscTQKc1M2SHlaZmlkVWp6NFcwbk5obUJDdGc1ZEVzWGl4bU5Kc3VBSW5TVkFvR0FIY0J0UUZ2QW9vUTNjbDdMME5GVAo4c0cvR04wbnRGdXJveE5oTlhaS3hYMGYrUXBWcHJFaTlybU13WXE1WXc3Z2lqZWdNNURUbUdFcHIvc1FNZmUyCjZYbjU5NmlLSFZ4NCtBZE90dnc5NnhlTm56S2syOVdrTENzbG4vZ2lETWJCcHowNFhDZ1h3TitEZXg3emVHSGkKNXFpWlpJSlNlS0gvR3BWcno5MEE3eU09Ci0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0K
```
Примените настройки:
```console
$ kubectl create -f tls-secret.yaml
```
5. Создайте ресурс VirtualServer для веб-приложения:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: webapp
spec:
host: webapp.example.com
tls:
secret: tls-secret
policies:
- name: ingress-mtls-policy
upstreams:
- name: webapp
service: webapp-svc
port: 80
routes:
- path: /
action:
pass: webapp
```
```console
$ kubectl apply -f virtual-server.yaml
```
#### NOTE
VirtualServer должен ссылаться на политику `ingress-mtls-policy`, созданную на шаге 3.
6. Протестируйте конфигурацию.
Если вы попытаетесь обратиться к приложению без предоставления клиентского сертификата и ключа, ANIC отклонит запрос:
```console
$ curl --insecure --resolve webapp.example.com:$IC_HTTPS_PORT:$IC_IP \
https://webapp.example.com:$IC_HTTPS_PORT/
```
Ожидаемый ответ:
```html
400 No required SSL certificate was sent
400 Bad Request
No required SSL certificate was sent
Angie/1.8.1
```
Если вы предоставите корректный клиентский сертификат и ключ, запрос выполнится успешно:
```console
$ curl --insecure --resolve webapp.example.com:$IC_HTTPS_PORT:$IC_IP \
https://webapp.example.com:$IC_HTTPS_PORT/ --cert ./client-cert.pem --key ./client-key.pem
```
Ожидаемый ответ:
```console
Server address: 10.244.0.8:8080
Server name: webapp-7c6d448df9-9ts8x
Date: 23/Sep/2020:07:18:52 +0000
URI: /
Request ID: acb0f48057ccdfd250debe5afe58252a
```
# https://angie.software/anic/docs/custom-resources/jwks.md
# JWKS
В этом примере:
- развертывается веб-приложение;
- настраивается балансировка нагрузки с помощью `VirtualServer`;
- применяется политика `JWT`.
В отличие от примера с `JWT`, здесь внешний провайдер идентификации (IdP) определен
с помощью поля `JwksURI`. В качестве провайдера используется `Keycloak`,
развернутый как контейнер и доступный с помощью ANIC.
## Предварительные действия
1. Установите ANIC.
2. Добавьте в файл `/etc/hosts` записи:
```text
<ваш_IP-адрес> webapp.example.com
<ваш_IP-адрес> keycloak.example.com
```
Здесь `webapp.example.com` — домен веб-приложения,
а `keycloak.example.com` — домен Keycloak.
## Настройка JWKS
1. Создайте Secret с TLS-сертификатом и ключом для терминального TLS-шифрования в `Keycloak`:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: tls-secret
type: kubernetes.io/tls
data:
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURFVENDQWZtZ0F3SUJBZ0lVS2hTQzBBcnhUblYrbjBhVnNENkFVTE5VQWhZd0RRWUpLb1pJaHZjTkFRRUwKQlFBd0dERVdNQlFHQTFVRUF3d05LaTVsZUdGdGNHeGxMbU52YlRBZUZ3MHlNVEF4TVRZd01qSXpNekZhRncwegpNVEF4TVRRd01qSXpNekZhTUJneEZqQVVCZ05WQkFNTURTb3VaWGhoYlhCc1pTNWpiMjB3Z2dFaU1BMEdDU3FHClNJYjNEUUVCQVFVQUE0SUJEd0F3Z2dFS0FvSUJBUURGeU1DSlhlSm9tMTdhcUVQc01NbTNlVzlpQzFHdlI4YW8KaDJhNmgvZWRXTUFndEtWSERmR2tPQ2V5NDBEdGtXTDN3U0NvZE1McnhPcnN2Lzhuc1VablFwQmNBekxBbzBJVgptYnhoS21WaS9EMkJpb2pBcDlqVXlsMjNma2RWMFdYM3NYV0JQekhSa3RyK0ozaW83YVcvNUl0WVBNWWFYM3dmCkZYRWFXVmQ4QmJDQ0hyVlZ3ckMvem9aTEF3dFE0d1I5NUI2NHdtd2d4TEhNZDlWZDRSZ1l2U0ppc1QzWi9IRkkKTGpaTGdMa0FlMGlDci9xdmFsdnVhU3BNVmJUd1lQZ2l6YWhXSVFTYjVyd29JeUhnYXFBWnRYSEhjNSsydDVoZQpMMDc2RjgrOE84b0hpdDR6WGpsR1V4TFNjTWFPTnI2ZHI0Q256NmlXZzJNTGlJcno0VnR4QWdNQkFBR2pVekJSCk1CMEdBMVVkRGdRV0JCUTdCSGpyZHlicnpWNHIwVkRrc2k3TXFPNWRKREFmQmdOVkhTTUVHREFXZ0JRN0JIanIKZHlicnpWNHIwVkRrc2k3TXFPNWRKREFQQmdOVkhSTUJBZjhFQlRBREFRSC9NQTBHQ1NxR1NJYjNEUUVCQ3dVQQpBNElCQVFDdm5TdUY4dUFUWFl2VHVjVGhEcG9jKzI5RU1LVFp2VDBmSmJrNWZMaWQzYjhFTDQxdk5tTjRwUTUrCmJtSFh1bkhLL29aSm43bWVNTngwc0ZQMW1Pa1U5MXBqZVJLWmoxOXVNQjlvTVBreXdXRENuQ1BHYWtFUHpxOS8KWjFwcERKQ0FJc2cvME8wZ1BCMDdFSm9RcU0wdDlZc3BuMlJ4djMwUGdBZ3ZuSXduUlNzUWpvOEpxQ1VuemZJLwpPdXovNVl1UkhJRHQzY0RpdTdzWG1DTW01cFJ5eUd2WGZiWEsrSVFWOHZDRTZlZS9FTlNFcnB0NUdzeVNURjZKCk5LdDhXM1VwNkUvL2dwMkRvTXBxS0tGQkE0aG5OQXVzQVphTkNQdi9EY0xueG9xQUp4S0V5cmpxelJBeTlCRXkKRzBhSTJ5bitKWW5yVW8wMmc1OWFXalZMTzg4RwotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUV2Z0lCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktnd2dnU2tBZ0VBQW9JQkFRREZ5TUNKWGVKb20xN2EKcUVQc01NbTNlVzlpQzFHdlI4YW9oMmE2aC9lZFdNQWd0S1ZIRGZHa09DZXk0MER0a1dMM3dTQ29kTUxyeE9ycwp2Lzhuc1VablFwQmNBekxBbzBJVm1ieGhLbVZpL0QyQmlvakFwOWpVeWwyM2ZrZFYwV1gzc1hXQlB6SFJrdHIrCkozaW83YVcvNUl0WVBNWWFYM3dmRlhFYVdWZDhCYkNDSHJWVndyQy96b1pMQXd0UTR3Ujk1QjY0d213Z3hMSE0KZDlWZDRSZ1l2U0ppc1QzWi9IRklMalpMZ0xrQWUwaUNyL3F2YWx2dWFTcE1WYlR3WVBnaXphaFdJUVNiNXJ3bwpJeUhnYXFBWnRYSEhjNSsydDVoZUwwNzZGOCs4TzhvSGl0NHpYamxHVXhMU2NNYU9OcjZkcjRDbno2aVdnMk1MCmlJcno0VnR4QWdNQkFBRUNnZ0VBQXhBcjR6VEFCK3k0R0Z6WXlIU3MreGwzWHlaYnVvSTdFbXNlYlM4ajU1enoKUk01bmJPVkxZOGEyM3E5a1Z3bVVaYy9vNkpMK1hkWnI2UVRFTitJbisvdHM3dS9odmxnSTh2cXhqek92NUV1Ugp6RXJQK1dQZ0dOT1ZoZnovcjlXUlpiZXE0VGlRVmZXWFRLNWgwUVAxT0RhYTdkL3JGWWQ3RGFRd1h6OFkrc080CnhqV0dNNFprOW1oWm1PbG9nZjNtYyszUFhYTWV6RFRMY2kzRWNpZVlaTkhTeXIzWkg2NU8rSkdsOFZ2bkZUWS8KQytQZi9tYmJKL282dlNWWDNWQUVIM29BY05qd1dqMkdBNUhiRk5RTnV0ckhRcnNkR0ZqUVB5aHNBYjNOV1h2bwo2M3hoS1NNbHpxSWd2WXZMbENOS0VjZmJsVjRuelJ4NVhhM0dzZjJkUFFLQmdRRDlYeEs4ekhpN2g4WjlQV2sxCktDZFlvZDFVa2ViWktYUVQvOUtNcmhrOE9abG1oV2hFK1lBY3lJRElVeFZuZ2xkR0d3RVViTFcyWEVnVStQVmEKM1ZlaUNCTlRWM3FwV3lYWXdIdG9yYm5WbGtlMGh4eE9WakhvSmpZWitmV0h6MDU0algvYkdsdWp5bVJGMWpoWApuMnhNUW5RUkV0S2FGN0R2d2FGK083dGExd0tCZ1FESDFndWRlVCsvQ3M1R3g3eEkwUnhwRUt4c0FtcUV3blBECklsaHoxZHJqbGZFaTRPZ25wK0ZOK05acGJiMHRaWmUyTTM2QXpMVENIUURmQVNJTlBDMkxzOHEvTjAyR2xzcG8KalVTd3M4cWc2N2ZjcG1UN1FVVTVMZmZuaDE3S1A5ZEdCdlRuK3Vza1MwVjRFZ2M0Ti9lS2pUQi9xcjYzYWRHUwp4dmRaYzdnNjl3S0JnRE9CQWdRUzVHL3FkN1M1cVFzL01GQmFCdTNNQXNzZUhCUjhxa1lpbGNxaVFzYU9VOVhCCmlnTlAxcTNpQmJYV3p2clhQbTd5Y2pXeHFJMXExaVUwWFQzNHVrVDB3V0J2d00vQXdOVlVpelFacWxYT0tUamIKV0tYQ0xyazFFRzRjKyt5Umh1MzQrNnZkMW1oRDFZd3FRZzkyYXJXVngrMis1eDYxazZoZmFBUmRBb0dCQU1Kcgp0QmM4VE5IQVlKb3FYenYwL3BBVm9icmZ5dVJwRHhsdFErTkd6OVFXSUduUHFPNVQvZmJQUDBPSmVjRStFeEU0CkhqNlBhdGxrUUdHMmgzdWE3YkQ2ZGluOVV4YTdoQ2VlTVpNOUNNbnhLNHVuODUwampvYW4rNFd0aFlKK0JDSmsKU0VlZUxzRzczZFdJcks5OGZBQzNodFRldVBoWElvZUx2a0N3UGpCWEFvR0JBUFBteVJJRGs5bUF5M2ZINnBtVwplRWlqYlBWbFdDd3FjalI5ZjQ0L3duVEpha0h4cVVxRk04cTVLNnJJejdPMmMvcDdmTm83andrVHc0R0hIVWcrCjQyVkpGOXRrdnRDbEhOZ3l6cXNjT3FjN0p2ZDNyYnBFbGVpNGgyTHo4Z0RDNFo4WldqWDBBKzVTaTlQd3RMaFEKN3pBZEJUMHk5WjZuNGYxMVg0UWhKSkR1Ci0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0K
```
Примените настройки:
```console
$ kubectl apply -f tls-secret.yaml
```
2. Создайте Deployment и Service для веб-приложения:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: webapp
spec:
replicas: 1
selector:
matchLabels:
app: webapp
template:
metadata:
labels:
app: webapp
spec:
containers:
- name: webapp
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: webapp-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: webapp
```
Примените настройки:
```console
$ kubectl apply -f webapp.yaml
```
3. Создайте Deployment и Service для `Keycloak`:
```yaml
apiVersion: v1
kind: Service
metadata:
name: keycloak
labels:
app: keycloak
spec:
ports:
- name: http
port: 8080
targetPort: 8080
selector:
app: keycloak
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: keycloak
namespace: default
labels:
app: keycloak
spec:
replicas: 1
selector:
matchLabels:
app: keycloak
template:
metadata:
labels:
app: keycloak
spec:
containers:
- name: keycloak
image: quay.io/keycloak/keycloak:20.0.1
args: ["start-dev"]
env:
- name: KEYCLOAK_ADMIN
value: "admin"
- name: KEYCLOAK_ADMIN_PASSWORD
value: "admin"
- name: KC_PROXY
value: "edge"
ports:
- name: http
containerPort: 8080
- name: https
containerPort: 8443
readinessProbe:
httpGet:
path: /realms/master
port: 8080
```
Примените настройки:
```console
$ kubectl apply -f keycloak.yaml
```
4. Создайте `VirtualServer` для Keycloak:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: keycloak
spec:
host: keycloak.example.com
tls:
secret: tls-secret
redirect:
enable: true
upstreams:
- name: keycloak
service: keycloak
port: 8080
routes:
- path: /
action:
pass: keycloak
```
Примените настройки:
```console
$ kubectl apply -f virtual-server-idp.yaml
```
5. Настройте Keycloak:
- Перейдите в Keycloak: `https://keycloak.example.com`.
- Создайте новую область `Realm` с именем `jwks-example`.
- Перейдите во вкладку `Client`, создайте новый клиент с именем `jwks-client` и
включите для него `Client authentication` и `Authorization`.
- Перейдите во вкладку `Credentials` и скопируйте секрет клиента.
Сохраните секрет:
```console
export SECRET=
```
- Перейдите во вкладку `Users` и создайте пользователя `jwks-user`.
- Перейдите во вкладку `Credentials` этого пользователя и установите пароль. Для примера подойдет любой пароль.
Сохраните пароль:
```console
export PASSWORD=
```
6. Создайте политику `jwt-policy` с указанием `JwksURI` и настройте поле `JwksURI` так,
чтобы оно разрешало только те запросы к веб-приложению, которые содержат действительный JWT.
В приведенной ниже политике замените область `jwks-example` на область (realm), созданную вами.
Значение `spec.jwt.token` в примере установлено в `$http_token`, так как токен клиента передается в заголовке HTTP.
```yaml
apiVersion: k8s.angie.software/v1
kind: Policy
metadata:
name: jwt-policy
spec:
jwt:
realm: MyProductAPI
token: $http_token
jwksURI: http://keycloak.default.svc.cluster.local:8080/realms/jwks-example/protocol/openid-connect/certs
```
Примените политику:
```console
$ kubectl apply -f jwks.yaml
```
7. Разверните ConfigMap с резолвером.
Если в `jwksURI` используется имя хоста, необходимо настроить `resolver`. Для этого необходимо добавить поле `resolver-addresses`.
```yaml
kind: ConfigMap
apiVersion: v1
metadata:
name: angie-config
namespace: angie-ingress
data:
resolver-addresses: kube-dns.kube-system.svc.cluster.local
http-snippets: |
subrequest_output_buffer_size 64k;
```
В этом примере мы создаем ConfigMap, используя стандартный DNS Kubernetes
`kube-dns.kube-system.svc.cluster.local` в качестве адреса резолвера.
Дополнительную информацию о `resolver-addresses` и других связанных
ключах ConfigMap можно посмотреть в разделе [ConfigMap](https://angie.software//anic/docs/configuration/configmap-resource.md#configmap-resource).
#### NOTE
При установке значения `jwksURI` ответ может отличаться в зависимости от используемого IDP.
В некоторых случаях ответ может быть слишком большим для корректной обработки Angie.
Если это произойдет, необходимо настроить директиву `subrequest_output_buffer_size` в контексте `http`.
Это можно сделать с помощью `http-snippets`.
Значение `subrequest_output_buffer_size` указано только для примера
и должно быть изменено в соответствии с вашей средой.
Примените конфигурацию:
```console
$ kubectl apply -f angie-config.yaml
```
8. Настройте балансировку нагрузки. Создайте `VirtualServer` для веб-приложения:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: webapp
spec:
host: webapp.example.com
policies:
- name: jwt-policy
upstreams:
- name: webapp
service: webapp-svc
port: 80
routes:
- path: /
action:
pass: webapp
```
Примените настройки:
```console
$ kubectl apply -f virtual-server.yaml
```
Обратите внимание, что `VirtualServer` ссылается на политику `jwt-policy`, созданную выше.
9. Получите токен клиента.
Для доступа к веб-приложению клиент должен передавать токен-носитель.
Чтобы получить токен, выполните команду:
```console
$ export TOKEN=$(curl -k -L -X POST 'https://keycloak.example.com/realms/jwks-example/protocol/openid-connect/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode grant_type=password \
--data-urlencode scope=openid \
--data-urlencode client_id=jwks-client \
--data-urlencode client_secret=$SECRET \
--data-urlencode username=jwks-user \
--data-urlencode password=$PASSWORD \
| jq -r .access_token)
```
Эта команда сохранит токен в переменной окружения TOKEN.
10. Протестируйте конфигурацию.
- Попытка запроса без токена-носителя:
```console
$ curl -H 'Accept: application/json' webapp.example.com
```
Ответ:
```html
401 Authorization Required
401 Authorization Required
Angie/1.8.1
```
- Запрос с корректным токеном-носителем:
```console
$ curl -H 'Accept: application/json' -H "token: ${TOKEN}" webapp.example.com
```
Ответ сервера:
```text
Server address: 10.42.0.7:8080
Server name: webapp-5c6fdbcbf9-pt9tp
Date: 13/Dec/2022:14:50:33 +0000
URI: /
Request ID: f1241390ac51318afa4fcc39d2341359
```
# https://angie.software/anic/docs/custom-resources/jwt.md
# JWT
В примере ниже развертывается веб-приложение, настраивается балансировка нагрузки с помощью `VirtualServer`
и применяется политика `JWT`.
## Предварительные действия
1. Установите ANIC.
2. Сохраните публичный IP-адрес ANIC в переменной оболочки:
```console
$ IC_IP=<ваш_IP-адрес>
```
3. Сохраните HTTP-порт ANIC в переменной оболочки:
```console
$ IC_HTTP_PORT=<номер порта>
```
## Настройка JWT
1. Создайте Deployment и Service для приложения:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: webapp
spec:
replicas: 1
selector:
matchLabels:
app: webapp
template:
metadata:
labels:
app: webapp
spec:
containers:
- name: webapp
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: webapp-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: webapp
```
Примените настройки:
```console
$ kubectl apply -f webapp.yaml
```
2. Создайте секрет с именем `jwk-secret`, который будет использоваться для проверки JWT:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: jwk-secret
type: angie.software/jwk
data:
jwk: eyJrZXlzIjoKICAgIFt7CiAgICAgICAgImsiOiJabUZ1ZEdGemRHbGphbmQwIiwKICAgICAgICAia3R5Ijoib2N0IiwKICAgICAgICAia2lkIjoiMDAwMSIKICAgIH1dCn0K
```
Примените настройки:
```console
$ kubectl apply -f jwk-secret.yaml
```
3. Создайте политику `jwt-policy`, которая будет ссылаться на `Secret` из предыдущего шага
и разрешать запросы к веб-приложению только при наличии корректного `JWT`:
```yaml
apiVersion: k8s.angie.software/v1
kind: Policy
metadata:
name: jwt-policy
spec:
jwt:
realm: MyProductAPI
secret: jwk-secret
token: $http_token
```
Примените настройки:
```console
$ kubectl apply -f jwt.yaml
```
4. Настройте балансировку нагрузки. Создайте ресурс `VirtualServer` для веб-приложения:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: webapp
spec:
host: webapp.example.com
policies:
- name: jwt-policy
upstreams:
- name: webapp
service: webapp-svc
port: 80
routes:
- path: /
action:
pass: webapp
```
Примените настройки:
```console
$ kubectl apply -f virtual-server.yaml
```
Обратите внимание, что `VirtualServer` ссылается на политику `jwt-policy`, созданную на предыдущем шаге.
5. Протестируйте конфигурацию.
Если попытаться получить доступ к приложению без `JWT`, ANIC отклонит запрос:
```console
$ curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT/
```
Ответ:
```html
401 Authorization Required
401 Authorization Required
Angie/1.8.1
```
Если передать корректный `JWT`, запрос будет выполнен успешно:
```console
$ curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT/ -H "token: `cat token.jwt`"
```
Ответ:
```text
Server address: 172.17.0.3:8080
Server name: webapp-7c6d448df9-lcrx6
Date: 10/Sep/2020:18:20:03 +0000
URI: /
Request ID: db2c07ce640755ccbe9f666d16f85620
```
# https://angie.software/anic/docs/custom-resources/configuring-oidc.md
# OIDC
OIDC (OpenID Connect) обеспечивает удобную аутентификацию пользователей через внешнего провайдера, используя безопасные токены для управления доступом в системе.
Политика OIDC настраивает ANIC как клиент (relying party) для аутентификации через OpenID Connect.
Например, следующая конфигурация использует clientID `myclient` и clientSecret `oidc-secret` для аутентификации через провайдера OpenID Connect `https://idp.example.com`:
```yaml
oidc:
clientID: myclient
clientSecret: oidc-secret
authEndpoint: https://idp.example.com/openid-connect/auth
jwksURI: https://idp.example.com/openid-connect/certs
tokenEndpoint: https://idp.example.com/openid-connect/token
scope: openid+profile+email
accessTokenEnable: true
```
Подробное описание параметров можно посмотреть [здесь](https://angie.software//anic/docs/configuration/policy-resource.md#oidc-policy).
## Настройка аутентификации через OpenID Connect
Чтобы настроить аутентификацию через OpenID Connect, выполните следующие шаги:
1. Задайте аргумент командной строки `enable-oidc=true`.
В конфиге будут подключены три модуля:
- `load_module modules/ngx_http_js_module.so;`
- `load_module modules/ngx_http_auth_jwt_module.so;`
- `load_module modules/ngx_http_keyval_module.so;`
2. Добавьте секрет с ключом клиента. Ключ должен быть закодирован в Base64:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: oidc-secret
type: angie.software/oidc
data:
client-secret:
```
3. Примените секрет:
```console
kubectl apply -f oidc/client-secret.yaml
```
4. Добавьте политику:
```yaml
apiVersion: k8s.angie.software/v1
kind: Policy
metadata:
name: oidc-policy
spec:
oidc:
clientID: myclient
clientSecret: oidc-secret
authEndpoint: https://idp.example.com/openid-connect/auth
jwksURI: https://idp.example.com/openid-connect/certs
tokenEndpoint: https://idp.example.com/openid-connect/token
scope: openid+profile+email
accessTokenEnable: true
```
5. Примените политику:
```console
kubectl apply -f oidc/oidc.yaml
```
6. После того как секрет и описание политики будут добавлены,
примените политику для сервера или маршрута, сославшись на нее:
```yaml
policies:
- name: oidc-policy
```
На данном этапе включение политики вызовет ошибку, т.к. не были заданы обязательные переменные, обеспечивающие валидацию токенов в процессе аутентификации OIDC:
- `$jwt_claim_iat`
- `$jwt_claim_iss`
- `$jwt_claim_sub`
- `$jwt_claim_aud`
7. В спецификации VirtualServer задайте обязательные
переменные в параметре [maps](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserver-maps):
```yaml
maps:
- variable: $jwt_claim_iat
source: $oidc_client
parameters:
- value: 'myclient'
result: '80'
- variable: $jwt_claim_iss
source: $oidc_client
parameters:
- value: 'myclient'
result: 'PROVIDER_URL'
- variable: $jwt_claim_sub
source: $oidc_client
parameters:
- value: 'myclient'
result: 'myclient'
- variable: $jwt_claim_aud
source: $oidc_client
parameters:
- value: 'myclient'
result: 'myclient'
```
В конфигурацию VirtualServer будут добавлены следующие директивы:
```nginx
map $oidc_client $jwt_claim_iat {
myclient 80;
}
map $oidc_client $jwt_claim_iss {
myclient PROVIDER_URL;
}
map $oidc_client $jwt_claim_sub {
myclient myclient;
}
map $oidc_client $jwt_claim_aud {
myclient myclient;
}
```
## Полный пример конфигурации
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: test-echo
spec:
host: test.example.com
upstreams:
- name: app-server-payload
service: echoserver
port: 8077
routes:
- path: /
action:
proxy:
upstream: app-server-payload
policies:
- name: oidc-policy
maps:
- variable: $jwt_claim_iat
source: $oidc_client
parameters:
- value: 'myclient'
result: '80'
- variable: $jwt_claim_iss
source: $oidc_client
parameters:
- value: 'myclient'
result: 'PROVIDER_URL'
- variable: $jwt_claim_sub
source: $oidc_client
parameters:
- value: 'myclient'
result: 'myclient'
- variable: $jwt_claim_aud
source: $oidc_client
parameters:
- value: 'myclient'
result: 'myclient'
```
## Пример включения переменных `map` в зависимости от входного значения
Значения:
- `default`
- `volatile`
- `include`
- `hostnames`
```yaml
maps:
- variable: $result_var
source: $host
parameters:
- value: 'default'
result: 'default_value'
- value: 'volatile'
result: ''
- value: 'include'
result: '/dev/stdout'
- value: 'example.com'
result: '1'
- value: '*.example.com'
result: '1'
```
См. также [директиву map](https://angie.software/configuration/modules/stream/stream_map/) в документации Angie.
# https://angie.software/anic/docs/custom-resources/tls-passthrough.md
# TLS Passthrough
Функция TLS Passthrough позволяет ANIC принимать TLS-соединения на порту 443
и направлять их на соответствующие серверы-бэкенды без расшифровки.
Маршрутизация осуществляется на основе SNI (Server Name Indication),
что позволяет клиентам указывать имя сервера (например, `example.com`) во время SSL-рукопожатия.
При этом ANIC продолжает обрабатывать обычный HTTPS-трафик на том же порту 443,
терминируя TLS-соединения с использованием сертификатов и ключей,
заданных в ресурсах `Ingress` или `VirtualServer`.
Ниже приведен пример использования ресурса `TransportServer`
для настройки балансировки нагрузки в режиме TLS Passthrough.
В примере будет развернуто бэкенд-приложение (Secure App), прослушивающее TLS-трафик на порту 8443.
ANIC будет маршрутизировать соединения к этому приложению с помощью `TransportServer`.
## О Secure App
Secure App — это под с Angie (не путать с подом ANIC,
который также использует Angie), настроенный на обслуживание HTTPS-трафика
на порту 8443 для хоста `app.example.com`.
Для терминации TLS используются самоподписанный TLS-сертификат и ключ.
Приложение отвечает на HTTPS-запросы клиентов простым текстовым сообщением:
```none
hello from pod <имя пода>
```
## Предварительные действия
1. Установите ANIC.
2. Убедитесь, что развернуто определение пользовательского ресурса для `TransportServer`.
3. Запустите ANIC с параметрами `-enable-custom-resources` и `-enable-tls-passthrough`,
чтобы включить поддержку TLS Passthrough.
4. Сохраните публичный IP-адрес ANIC в переменной оболочки:
```console
$ IC_IP=<ваш_IP-адрес>
```
5. Сохраните HTTPS-порт ANIC в переменной оболочки:
```console
$ IC_HTTPS_PORT=<номер порта>
```
## Настройка TLS Passthrough
1. Разверните Secure App:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: secure-app
spec:
replicas: 1
selector:
matchLabels:
app: secure-app
template:
metadata:
labels:
app: secure-app
spec:
containers:
- name: secure-app
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8443
volumeMounts:
- name: secret
mountPath: /etc/angie/ssl
readOnly: true
- name: config-volume
mountPath: /etc/angie/conf.d
volumes:
- name: secret
secret:
secretName: app-tls-secret
- name: config-volume
configMap:
name: secure-config
---
apiVersion: v1
kind: Service
metadata:
name: secure-app
spec:
ports:
- port: 8443
targetPort: 8443
protocol: TCP
name: https
selector:
app: secure-app
---
apiVersion: v1
kind: ConfigMap
metadata:
name: secure-config
data:
app.conf: |-
server {
listen 8443 ssl;
listen [::]:8443 ssl;
server_name app.example.com;
ssl_certificate /etc/angie/ssl/tls.crt;
ssl_certificate_key /etc/angie/ssl/tls.key;
default_type text/plain;
location / {
return 200 "hello from pod $hostname\n";
}
}
---
apiVersion: v1
kind: Secret
metadata:
name: app-tls-secret
data:
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURGRENDQWZ3Q0NRQ3EzQWxhdnJiaWpqQU5CZ2txaGtpRzl3MEJBUXNGQURCTU1Rc3dDUVlEVlFRR0V3SlYKVXpFTE1Ba0dBMVVFQ0F3Q1EwRXhGakFVQmdOVkJBY01EVk5oYmlCR2NtRnVZMmx6WTI4eEdEQVdCZ05WQkFNTQpEMkZ3Y0M1bGVHRnRjR3hsTG1OdmJUQWVGdzB5TURBek1qTXlNekl3TkROYUZ3MHlNekF6TWpNeU16SXdORE5hCk1Fd3hDekFKQmdOVkJBWVRBbFZUTVFzd0NRWURWUVFJREFKRFFURVdNQlFHQTFVRUJ3d05VMkZ1SUVaeVlXNWoKYVhOamJ6RVlNQllHQTFVRUF3d1BZWEJ3TG1WNFlXMXdiR1V1WTI5dE1JSUJJakFOQmdrcWhraUc5dzBCQVFFRgpBQU9DQVE4QU1JSUJDZ0tDQVFFQTJCRXhZR1JPRkhoN2VPMVlxeCtWRHMzRzMrVEhyTEZULzdEUFFEQlkza3pDCi9oZlprWCt3OW1NNkQ1RU9uK2lpVlNhUWlQMm1aNFA3N29pR0dmd3JrNjJ0eEQ5cHphODM5NC9aSjF5Q0dXZ1QKK2NWUEVZbkxjQktzSTRMcktJZ21oWVIwUjNzWWRjR1JkSXJWUFZlNUVUQlk1Z1U0RGhhMDZOUEIraitmK0krWgphWGIvMlRBekJhNHozMWpIQzg2amVQeTFMdklGazFiY3I2cSsxRGR5eklxcWxkRDYvU3Q4Q2t3cDlOaDFCUGFhCktZZ1ZVd010UVBib2s1cFFmbVMrdDg4NHdSM0dTTEU4VkxRbzgyYnJhNUR3emhIamlzOTlJRGhzbUt0U3lWOXMKaWNJbXp5dHBnSXlhTS9zWEhRQU9KbVFJblFteWgyekd1WFhTQ0lkRGtRSURBUUFCTUEwR0NTcUdTSWIzRFFFQgpDd1VBQTRJQkFRQ0tsVkhOZ1k5VHZLaW9Xb0tvdllCdnNRMmYrcmFOOEJwdWNDcnRvRm15NUczcGIzU2lPTndaCkF2cnhtSm4vR3lsa3JKTHBpQVA1eUNBNGI2Y2lYMnRGa3pQRmhJVFZKRTVBeDlpaEF2WWZwTUFSdWVqM29HN2UKd0xwQk1iUnlGbHJYV29NWUVBMGxsV0JueHRQQXZYS2Y4SVZGYTRSSDhzV1JJSDB4M2hFdjVtQ3VUZjJTRTg0QwpiNnNjS3Z3MW9CQU5VWGxXRVZVYTFmei9rWWZBa1lrdHZyV2JUcTZTWGxodXRJYWY4WEYzSUMrL2x1b3gzZThMCjBBcEFQVE5sZ0JwOTkvcXMrOG9PMWthSmQ1TmV6TnlJeXhSdUtJMzlDWkxuQm9OYmkzdlFYY1NzRCtYU2lYT0cKcEVnTjNtci8xRms4OVZMSENhTnkyKzBqMjZ0eWpiclcKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=
tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUV2Z0lCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktnd2dnU2tBZ0VBQW9JQkFRRFlFVEZnWkU0VWVIdDQKN1Zpckg1VU96Y2JmNU1lc3NWUC9zTTlBTUZqZVRNTCtGOW1SZjdEMll6b1BrUTZmNktKVkpwQ0kvYVpuZy92dQppSVlaL0N1VHJhM0VQMm5OcnpmM2o5a25YSUlaYUJQNXhVOFJpY3R3RXF3amd1c29pQ2FGaEhSSGV4aDF3WkYwCml0VTlWN2tSTUZqbUJUZ09GclRvMDhINlA1LzRqNWxwZHYvWk1ETUZyalBmV01jTHpxTjQvTFV1OGdXVFZ0eXYKcXI3VU4zTE1pcXFWMFByOUszd0tUQ24wMkhVRTlwb3BpQlZUQXkxQTl1aVRtbEIrWkw2M3p6akJIY1pJc1R4VQp0Q2p6WnV0cmtQRE9FZU9LejMwZ09HeVlxMUxKWDJ5SndpYlBLMm1Bakpveit4Y2RBQTRtWkFpZENiS0hiTWE1CmRkSUloME9SQWdNQkFBRUNnZ0VCQUxYaW16ODZrT1A0bkhBcTFPYVEyb2l3dndhQTczbTNlUytZSm84eFk4NFcKcmxyNXRzUWR5dGxPcEhTd05yQjBSQnNNTU1XeFNPQ0JJWlltUlVVZ200cGd2Uk9rRWl2OG9VOThQMkE4SnFTKwprWHBFRjVCNi84K2pXRmM0Z1Q4SWhlMEZtR0VJQllvelhYL08wejBsV0h4WXg2MHluWUoycU9vS1FKT3A5YjlsCmpiUVBkaC9mN2ErRWF0RzZNUFlrNG5xSEY3a0FzcmNsRXo2SGUvaEx6NmRkSTJ1N2RMRjB6QlN0QjM5WDFRZysKZ1JzTittOXg1S1FVTXYxMktvajdLc2hEelozOG5hSjd5bDgycGhBV1lGZzBOZHlzRlBRbmt0WmlNSUxOblFjNwpOeUt0cHNQaUxIRE9ha05hdEZLU2lOaUJrUk1lY1ZUMlJNMzMzUG54bFVFQ2dZRUEvYTY5MEEralU4VFJNbVZyCk4vRnlYWkxYa1c5b2NxVjBRbTA0TDMrSExybFNCTlRWSzk2U1pVT203VjViTzIxNmd4S2dJK3IwYm5kdE5GTUQKLzFncDhsdlJNcUlIeGZTeUo4SHpsSzViT0lnaUpxRGhzK3BKWTZmLytIVzZ1QkZyN3NGS3lxbVlIQlA0SC9BdApsT3lLeEVjMHFXazFlT2tCMWNNSGx0WDRwemtDZ1lFQTJncDhDVDVYWjNMSWRQN2M1SHpDS1YwczBYS1hGNmYyCkxzclhPVlZaTmJCN1NIS1NsOTBIU2VWVGx3czdqSnNxcC9yWFY2aHF0eUdEaTg4aTFZekthcEF6dXl3b0U3TnEKMUJpd2ZYSURQeTlPNUdGNXFYNXFUeENzSWNIcmo2Z21XMEZVQWhoS1lQcDRxd1JMdzFMZkJsd3U1VmhuN3I3ego0SkZBTEFpdlp4a0NnWUJicnpuKzVvZjdFSmtqQTdDYWlYTHlDczVLUzkrTi8rcGl6NktNMkNSOWFKRVNHZkhwClp3bTErNXRyRXIwYVgxajE0bGRxWTlKdjBrM3ZxVWs2a2h5bThUUk1mbThjeG5GVkdTMzF3SVpMaWpmOWlndkkKd0paQnBFaEkvaE83enVBWmJGYWhwR1hMVUJSUFJyalNxQ01IQ1UwcEpWTWtIZUtCNVhqcXRPNm5VUUtCZ0NJUAp6VHlzYm44TW9XQVZpSEJ4Uk91dFVKa1BxNmJZYUU3N0JSQkIwd1BlSkFRM1VjdERqaVh2RzFYWFBXQkR4VEFrCnNZdFNGZ214eEprTXJNWnJqaHVEbDNFLy9xckZOb1VYcmtxS2l4Tk4wcWMreXdDOWJPSVpHcXJUWG5jOHIzRkcKRFZlZWI5QWlrTU0ya3BkYTFOaHJnaS8xMVphb1lmVE0vQmRrNi9IUkFvR0JBSnFzTmFZYzE2clVzYzAzUEwybApXUGNzRnZxZGI3SEJyakVSRkhFdzQ0Vkt2MVlxK0ZWYnNNN1FTQVZ1V1llcGxGQUpDYzcrSEt1YjRsa1hRM1RkCndSajJLK2pOUzJtUXp1Y2hOQnlBZ1hXVnYveHhMZEE3NnpuWmJYdjl5cXhnTVVjTVZwZGRuSkxVZm9QVVZ1dTcKS0tlVVU3TTNIblRKUStrcldtbUxraUlSCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0K
```
Примените настройки:
```console
$ kubectl apply -f secure-app.yaml
```
2. Настройте балансировку нагрузки.
Создайте ресурс `TransportServer`:
```yaml
apiVersion: k8s.angie.software/v1alpha1
kind: TransportServer
metadata:
name: secure-app
spec:
listener:
name: tls-passthrough
protocol: TLS_PASSTHROUGH
host: app.example.com
upstreams:
- name: secure-app
service: secure-app
port: 8443
action:
pass: secure-app
```
Примените настройки:
```console
$ kubectl apply -f transport-server-passthrough.yaml
```
3. Проверьте успешность применения конфигурации, просмотрев события `TransportServer`:
```console
$ kubectl describe ts secure-app
```
Вывод команды может выглядеть так:
```console
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal AddedOrUpdated 9s anic Configuration for default/secure-app was added or updated
```
4. Проверьте доступ к Secure App с помощью `curl`. Используйте параметр `--insecure`,
чтобы отключить проверку сертификатов (так как используется самоподписанный сертификат),
а также `--resolve`, чтобы указать IP-адрес и HTTPS-порт ANIC для домена `app.example.com`:
```console
$ curl --resolve app.example.com:$IC_HTTPS_PORT:$IC_IP https://app.example.com:$IC_HTTPS_PORT --insecure
```
Ожидаемый ответ:
```console
hello from pod secure-app-d986bcf6b-jwm2s
```
# https://angie.software/anic/docs/ingress-resources.md
# Примеры для Ingress-ресурсов
В этом разделе собраны примеры настройки и типовые конфигурации для Ingress-ресурсов.
[Базовая конфигурация](https://angie.software//anic/docs/ingress-resources/complete-example.md#i-complete-example)
[Базовая HTTP-аутентификация](https://angie.software//anic/docs/ingress-resources/basic-auth.md#i-basic-auth)
[Объединяемые типы Ingress-ресурсов](https://angie.software//anic/docs/ingress-resources/mergeable-ingress-types.md#i-mergeable-ingress)
[Поддержка переписывания (rewrites)](https://angie.software//anic/docs/ingress-resources/rewrites.md#i-rewrites)
[Пользовательские шаблоны](https://angie.software//anic/docs/ingress-resources/custom-template.md#i-custom-templates)
[Развертывание ANIC как DaemonSet](https://angie.software//anic/docs/ingress-resources/daemon-set.md#i-daemon-set)
[Сохранение сессий](https://angie.software//anic/docs/ingress-resources/session-persistence.md#i-session-persistence)
[gRPC](https://angie.software//anic/docs/ingress-resources/grpc-services.md#i-grpc-services)
[SSL-сервисы](https://angie.software//anic/docs/ingress-resources/ssl-services.md#i-ssl-services)
[TCP- и UDP-балансировка для DNS](https://angie.software//anic/docs/ingress-resources/tcp-udp.md#i-tcp-udp)
[WebSocket](https://angie.software//anic/docs/ingress-resources/websocket.md#i-websocket)
# https://angie.software/anic/docs/ingress-resources/complete-example.md
# Базовая конфигурация
В этой статье приведен пример базовой конфигурации балансировки нагрузки для приложения
с помощью ресурса Ingress.
1. Установите ANIC.
2. Сохраните публичный IP-адрес ANIC в переменной оболочки:
```console
$ IC_IP=<ваш_IP-адрес>
```
3. Сохраните HTTP-порт ANIC в переменную оболочки:
```console
$ IC_HTTP_PORT=<номер_порта>
```
4. Создайте Deployment и Service приложения Cafe для компонентов `coffee` и `tea`:
### Пример
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: coffee
spec:
replicas: 2
selector:
matchLabels:
app: coffee
template:
metadata:
labels:
app: coffee
spec:
containers:
- name: coffee
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: coffee-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: coffee
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: tea
spec:
replicas: 3
selector:
matchLabels:
app: tea
template:
metadata:
labels:
app: tea
spec:
containers:
- name: tea
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: tea-svc
labels:
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: tea
```
Примените настройки:
```console
$ kubectl create -f cafe.yaml
```
5. Создайте секрет с SSL-сертификатом:
### Пример
```yaml
apiVersion: v1
kind: Secret
metadata:
name: cafe-secret
type: kubernetes.io/tls
data:
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURMakNDQWhZQ0NRREFPRjl0THNhWFdqQU5CZ2txaGtpRzl3MEJBUXNGQURCYU1Rc3dDUVlEVlFRR0V3SlYKVXpFTE1Ba0dBMVVFQ0F3Q1EwRXhJVEFmQmdOVkJBb01HRWx1ZEdWeWJtVjBJRmRwWkdkcGRITWdVSFI1SUV4MApaREViTUJrR0ExVUVBd3dTWTJGbVpTNWxlR0Z0Y0d4bExtTnZiU0FnTUI0WERURTRNRGt4TWpFMk1UVXpOVm9YCkRUSXpNRGt4TVRFMk1UVXpOVm93V0RFTE1Ba0dBMVVFQmhNQ1ZWTXhDekFKQmdOVkJBZ01Ba05CTVNFd0h3WUQKVlFRS0RCaEpiblJsY201bGRDQlhhV1JuYVhSeklGQjBlU0JNZEdReEdUQVhCZ05WQkFNTUVHTmhabVV1WlhoaApiWEJzWlM1amIyMHdnZ0VpTUEwR0NTcUdTSWIzRFFFQkFRVUFBNElCRHdBd2dnRUtBb0lCQVFDcDZLbjdzeTgxCnAwanVKL2N5ayt2Q0FtbHNmanRGTTJtdVpOSzBLdGVjcUcyZmpXUWI1NXhRMVlGQTJYT1N3SEFZdlNkd0kyaloKcnVXOHFYWENMMnJiNENaQ0Z4d3BWRUNyY3hkam0zdGVWaVJYVnNZSW1tSkhQUFN5UWdwaW9iczl4N0RsTGM2SQpCQTBaalVPeWwwUHFHOVNKZXhNVjczV0lJYTVyRFZTRjJyNGtTa2JBajREY2o3TFhlRmxWWEgySTVYd1hDcHRDCm42N0pDZzQyZitrOHdnemNSVnA4WFprWldaVmp3cTlSVUtEWG1GQjJZeU4xWEVXZFowZXdSdUtZVUpsc202OTIKc2tPcktRajB2a29QbjQxRUUvK1RhVkVwcUxUUm9VWTNyemc3RGtkemZkQml6Rk8yZHNQTkZ4MkNXMGpYa05MdgpLbzI1Q1pyT2hYQUhBZ01CQUFFd0RRWUpLb1pJaHZjTkFRRUxCUUFEZ2dFQkFLSEZDY3lPalp2b0hzd1VCTWRMClJkSEliMzgzcFdGeW5acS9MdVVvdnNWQTU4QjBDZzdCRWZ5NXZXVlZycTVSSWt2NGxaODFOMjl4MjFkMUpINnIKalNuUXgrRFhDTy9USkVWNWxTQ1VwSUd6RVVZYVVQZ1J5anNNL05VZENKOHVIVmhaSitTNkZBK0NuT0Q5cm4yaQpaQmVQQ0k1ckh3RVh3bm5sOHl3aWozdnZRNXpISXV5QmdsV3IvUXl1aTlmalBwd1dVdlVtNG52NVNNRzl6Q1Y3ClBwdXd2dWF0cWpPMTIwOEJqZkUvY1pISWc4SHc5bXZXOXg5QytJUU1JTURFN2IvZzZPY0s3TEdUTHdsRnh2QTgKN1dqRWVxdW5heUlwaE1oS1JYVmYxTjM0OWVOOThFejM4Zk9USFRQYmRKakZBL1BjQytHeW1lK2lHdDVPUWRGaAp5UkU9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBcWVpcCs3TXZOYWRJN2lmM01wUHJ3Z0pwYkg0N1JUTnBybVRTdENyWG5LaHRuNDFrCkcrZWNVTldCUU5semtzQndHTDBuY0NObzJhN2x2S2wxd2k5cTIrQW1RaGNjS1ZSQXEzTVhZNXQ3WGxZa1YxYkcKQ0pwaVJ6ejBza0lLWXFHN1BjZXc1UzNPaUFRTkdZMURzcGRENmh2VWlYc1RGZTkxaUNHdWF3MVVoZHErSkVwRwp3SStBM0kreTEzaFpWVng5aU9WOEZ3cWJRcCt1eVFvT05uL3BQTUlNM0VWYWZGMlpHVm1WWThLdlVWQ2cxNWhRCmRtTWpkVnhGbldkSHNFYmltRkNaYkp1dmRySkRxeWtJOUw1S0Q1K05SQlAvazJsUkthaTAwYUZHTjY4NE93NUgKYzMzUVlzeFR0bmJEelJjZGdsdEkxNURTN3lxTnVRbWF6b1Z3QndJREFRQUJBb0lCQVFDUFNkU1luUXRTUHlxbApGZlZGcFRPc29PWVJoZjhzSStpYkZ4SU91UmF1V2VoaEp4ZG01Uk9ScEF6bUNMeUw1VmhqdEptZTIyM2dMcncyCk45OUVqVUtiL1ZPbVp1RHNCYzZvQ0Y2UU5SNThkejhjbk9SVGV3Y290c0pSMXBuMWhobG5SNUhxSkpCSmFzazEKWkVuVVFmY1hackw5NGxvOUpIM0UrVXFqbzFGRnM4eHhFOHdvUEJxalpzVjdwUlVaZ0MzTGh4bndMU0V4eUZvNApjeGI5U09HNU9tQUpvelN0Rm9RMkdKT2VzOHJKNXFmZHZ5dGdnOXhiTGFRTC94MGtwUTYyQm9GTUJEZHFPZVBXCktmUDV6WjYvMDcvdnBqNDh5QTFRMzJQem9idWJzQkxkM0tjbjMyamZtMUU3cHJ0V2wrSmVPRmlPem5CUUZKYk4KNHFQVlJ6NWhBb0dCQU50V3l4aE5DU0x1NFArWGdLeWNrbGpKNkY1NjY4Zk5qNUN6Z0ZScUowOXpuMFRsc05ybwpGVExaY3hEcW5SM0hQWU00MkpFUmgySi9xREZaeW5SUW8zY2czb2VpdlVkQlZHWTgrRkkxVzBxZHViL0w5K3l1CmVkT1pUUTVYbUdHcDZyNmpleHltY0ppbS9Pc0IzWm5ZT3BPcmxEN1NQbUJ2ek5MazRNRjZneGJYQW9HQkFNWk8KMHA2SGJCbWNQMHRqRlhmY0tFNzdJbUxtMHNBRzR1SG9VeDBlUGovMnFyblRuT0JCTkU0TXZnRHVUSnp5K2NhVQprOFJxbWRIQ2JIelRlNmZ6WXEvOWl0OHNaNzdLVk4xcWtiSWN1YytSVHhBOW5OaDFUanNSbmU3NFowajFGQ0xrCmhIY3FIMHJpN1BZU0tIVEU4RnZGQ3haWWRidUI4NENtWmlodnhicFJBb0dBSWJqcWFNWVBUWXVrbENkYTVTNzkKWVNGSjFKelplMUtqYS8vdER3MXpGY2dWQ0thMzFqQXdjaXowZi9sU1JxM0hTMUdHR21lemhQVlRpcUxmZVpxYwpSMGlLYmhnYk9jVlZrSkozSzB5QXlLd1BUdW14S0haNnpJbVpTMGMwYW0rUlk5WUdxNVQ3WXJ6cHpjZnZwaU9VCmZmZTNSeUZUN2NmQ21mb09oREN0enVrQ2dZQjMwb0xDMVJMRk9ycW40M3ZDUzUxemM1em9ZNDR1QnpzcHd3WU4KVHd2UC9FeFdNZjNWSnJEakJDSCtULzZzeXNlUGJKRUltbHpNK0l3eXRGcEFOZmlJWEV0LzQ4WGY2ME54OGdXTQp1SHl4Wlp4L05LdER3MFY4dlgxUE9ucTJBNWVpS2ErOGpSQVJZS0pMWU5kZkR1d29seHZHNmJaaGtQaS80RXRUCjNZMThzUUtCZ0h0S2JrKzdsTkpWZXN3WEU1Y1VHNkVEVXNEZS8yVWE3ZlhwN0ZjanFCRW9hcDFMU3crNlRYcDAKWmdybUtFOEFSek00NytFSkhVdmlpcS9udXBFMTVnMGtKVzNzeWhwVTl6WkxPN2x0QjBLSWtPOVpSY21Vam84UQpjcExsSE1BcWJMSjhXWUdKQ2toaVd4eWFsNmhZVHlXWTRjVmtDMHh0VGwvaFVFOUllTktvCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==
```
Примените настройки:
```console
$ kubectl create -f cafe-secret.yaml
```
6. Создайте ресурс Ingress:
### Пример
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress
spec:
ingressClassName: angie
tls:
- hosts:
- cafe.example.com
secretName: cafe-secret
rules:
- host: cafe.example.com
http:
paths:
- path: /tea
pathType: Prefix
backend:
service:
name: tea-svc
port:
number: 80
- path: /coffee
pathType: Prefix
backend:
service:
name: coffee-svc
port:
number: 80
```
Примените настройки:
```console
$ kubectl create -f cafe-ingress.yaml
```
7. Протестируйте конфигурацию.
Для доступа к приложению используйте утилиту **curl**.
Параметр `--insecure` нужен для отключения проверки самоподписанного SSL-сертификата,
а `--resolve` — для того, чтобы задать IP-адрес и порт Ingress-контроллера для домена `cafe.example.com`.
Чтобы получить `coffee`:
```console
$ curl --resolve cafe.example.com:$IC_HTTPS_PORT:$IC_IP
https://cafe.example.com:$IC_HTTPS_PORT/coffee --insecure
```
Ожидаемый результат:
```console
Server address: 10.12.0.18:80
Server name: coffee-7586895968-r26zn
...
```
Чтобы получить `tea`:
```console
$ curl --resolve cafe.example.com:$IC_HTTPS_PORT:$IC_IP
https://cafe.example.com:$IC_HTTPS_PORT/tea --insecure
```
Ожидаемый результат:
```console
Server address: 10.12.0.19:80
Server name: tea-7cd44fcb4d-xfw2x
...
```
Базовую информацию о состоянии сервера можно просмотреть также на [странице Stub Status](https://angie.software//anic/docs/logging-and-monitoring/status-page.md#status-page-anic).
# https://angie.software/anic/docs/ingress-resources/basic-auth.md
# Базовая HTTP-аутентификация
ANIC поддерживает аутентификацию HTTP-запросов.
Для настройки базовой HTTP-аутентификации используются следующие две аннотации:
- `angie.software/basic-auth-secret: "secret"` — обязательная аннотация,
указывает на секрет, содержащий список пользователей в формате `htpasswd`.
Значения хранятся в поле `htpasswd`. Тип секрета: `angie.software/htpasswd`.
- `angie.software/basic-auth-realm: "realm"` — необязательная аннотация,
определяет область (realm), отображаемую в окне входа.
1. Установите ANIC.
2. Сохраните публичный IP-адрес ANIC в переменной оболочки:
```console
$ IC_IP=<ваш_IP-адрес>
```
3. Сохраните HTTP-порт ANIC в переменную оболочки:
```console
$ IC_HTTP_PORT=<номер_порта>
```
4. Создайте Deployment и Service приложения Cafe для компонентов `coffee` и `tea`:
### Пример
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: coffee
spec:
replicas: 2
selector:
matchLabels:
app: coffee
template:
metadata:
labels:
app: coffee
spec:
containers:
- name: coffee
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: coffee-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: coffee
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: tea
spec:
replicas: 3
selector:
matchLabels:
app: tea
template:
metadata:
labels:
app: tea
spec:
containers:
- name: tea
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: tea-svc
labels:
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: tea
```
Примените настройки:
```console
$ kubectl apply -f cafe.yaml
```
5. Создайте секрет типа `angie.software/htpasswd` с именем `cafe-passwd`,
который будет использоваться для базовой аутентификации.
Секрет должен содержать список пар `user:password` в формате Base64:
```yaml
kind: Secret
metadata:
name: cafe-passwd
apiVersion: v1
type: angie.software/htpasswd
stringData:
htpasswd: |
foo:$2y$10$e4CiBWaLq9JW93jV8r9CW.RE6fbsT3szmIsUhwqYuPfVlggXiBY76
# bar
```
Примените настройки:
```console
$ kubectl apply -f cafe-passwd.yaml
```
6. Создайте ресурс Ingress для приложения:
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress
annotations:
angie.software/basic-auth-secret: "cafe-passwd"
angie.software/basic-auth-realm: "Cafe App"
spec:
ingressClassName: angie
tls:
- hosts:
- cafe.example.com
secretName: cafe-secret
rules:
- host: cafe.example.com
http:
paths:
- path: /tea
pathType: Prefix
backend:
service:
name: tea-svc
port:
number: 80
- path: /coffee
pathType: Prefix
backend:
service:
name: coffee-svc
port:
number: 80
```
Примените настройки:
```console
$ kubectl apply -f cafe-ingress.yaml
```
#### NOTE
Ресурс Ingress должен содержать аннотацию `angie.software/basic-auth-secret`,
ссылающуюся на секрет `cafe-passwd`, созданный ранее.
7. Протестируйте конфигурацию.
Если вы попытаетесь получить доступ к приложению без указания
действительных имени пользователя и пароля, ANIC отклонит запрос:
```console
$ curl --resolve cafe.example.com:$IC_HTTP_PORT:$IC_IP http://cafe.example.com:$IC_HTTP_PORT/
401 Authorization Required
401 Authorization Required
Angie/1.8.1
```
Если указать правильные имя пользователя и пароль, запрос будет успешным:
```console
$ curl --resolve cafe.example.com:$IC_HTTPS_PORT:$IC_IP https://cafe.example.com:$IC_HTTPS_PORT/coffee --insecure -u foo:bar
Server address: 10.244.0.6:8080
Server name: coffee-7b9b4bbd99-bdbxm
Date: 20/Jun/2022:11:43:34 +0000
URI: /coffee
Request ID: f91f15d1af17556e552557df2f5a0dd2
```
## Пример с отдельными параметрами htpasswd для разных путей
В примере ниже реализована базовая аутентификация для [объединенных (mergeable) ресурсов Ingress](https://angie.software//anic/docs/ingress-resources/mergeable-ingress-types.md#i-mergeable-ingress)
с отдельными списками `user:password` для каждого пути.
Master Ingress:
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress-master
annotations:
angie.software/mergeable-ingress-type: "master"
spec:
ingressClassName: angie
tls:
- hosts:
- cafe.example.com
secretName: cafe-secret
rules:
- host: cafe.example.com
```
Minion для `/tea`:
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress-tea-minion
annotations:
angie.software/mergeable-ingress-type: "minion"
angie.software/basic-auth-secret: "tea-passwd"
angie.software/basic-auth-realm: "Tea"
spec:
rules:
- host: cafe.example.com
http:
paths:
- path: /tea
pathType: Prefix
backend:
service:
name: tea-svc
port:
number: 80
```
Minion для `/coffee`:
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress-coffee-minion
annotations:
angie.software/mergeable-ingress-type: "minion"
angie.software/basic-auth-secret: "coffee-passwd"
angie.software/basic-auth-realm: "Coffee"
spec:
rules:
- host: cafe.example.com
http:
paths:
- path: /coffee
pathType: Prefix
backend:
service:
name: coffee-svc
port:
number: 80
```
# https://angie.software/anic/docs/ingress-resources/mergeable-ingress-types.md
# Объединяемые типы Ingress-ресурсов
Вы можете распространить конфигурацию Ingress на несколько ресурсов Ingress на одном хосте,
используя аннотацию `angie.software/mergeable-ingress-type`.
Ресурсы могут находиться в одном или в разных пространствах имен,
что упрощает управление при большом количестве путей.
## Синтаксис и правила
### Ресурс Master Ingress
Ресурс Master Ingress задается с помощью аннотации `angie.software/mergeable-ingress-type: master`.
Master будет обрабатывать все конфигурации на уровне хоста, включая TLS-настройки и аннотации,
применяемые ко всему хосту. У одного хоста может быть только один Ingress-ресурс типа Master.
В ресурсе Master нельзя указывать пути. У одного Master-ресурса может быть
несколько ресурсов Minion, при условии, что их пути не конфликтуют.
При конфликте будет выбран путь, который задан в самом старом ресурсе Minion.
Ресурс Master не может содержать следующие аннотации:
- `angie.software/rewrites`
- `angie.software/ssl-services`
- `angie.software/grpc-services`
- `angie.software/websocket-services`
- `angie.software/sticky-cookie-services`
- `angie.software/health-checks`
- `angie.software/health-checks-mandatory`
- `angie.software/health-checks-mandatory-queue`
### Ресурс Minion Ingress
Ресурс Minion Ingress задается с помощью аннотации `angie.software/mergeable-ingress-type: minion`.
Ресурс Minion добавляет разные пути к Ingress-ресурсу типа Master.
В Minion Ingress нельзя задать TLS-настройки.
Ресурс Minion не может содержать следующие аннотации:
- `angie.software/proxy-hide-headers`
- `angie.software/proxy-pass-headers`
- `angie.software/redirect-to-https`
- `ingress.kubernetes.io/ssl-redirect`
- `angie.software/hsts`
- `angie.software/hsts-max-age`
- `angie.software/hsts-include-subdomains`
- `angie.software/server-tokens`
- `angie.software/listen-ports`
- `angie.software/listen-ports-ssl`
- `angie.software/server-snippets`
Ресурс Minion наследует следующие аннотации от Master-ресурса, если они в нем не переопределены:
- `angie.software/proxy-connect-timeout`
- `angie.software/proxy-read-timeout`
- `angie.software/client-max-body-size`
- `angie.software/proxy-buffering`
- `angie.software/proxy-buffers`
- `angie.software/proxy-buffer-size`
- `angie.software/proxy-max-temp-file-size`
- `angie.software/location-snippets`
- `angie.software/lb-method`
- `angie.software/keepalive`
- `angie.software/max-fails`
- `angie.software/fail-timeout`
#### NOTE
Нельзя использовать ресурсы Ingress, у которых больше одного хоста.
## Пример
В этом примере разворачивается ANIC и простое веб-приложение, а также создаются ресурсы
Master и Minion для настройки балансировщика нагрузки с помощью аннотации `angie.software/mergeable-ingress-type`.
1. Установите ANIC.
2. Сохраните публичный IP-адрес ANIC в переменной оболочки:
```console
$ IC_IP=<ваш_IP-адрес>
```
3. Сохраните HTTP-порт ANIC в переменную оболочки:
```console
$ IC_HTTP_PORT=<номер_порта>
```
4. Создайте Deployment и Service приложения Cafe для компонентов `coffee` и `tea`:
### Пример
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: coffee
spec:
replicas: 2
selector:
matchLabels:
app: coffee
template:
metadata:
labels:
app: coffee
spec:
containers:
- name: coffee
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: coffee-svc
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: coffee
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: tea
spec:
replicas: 3
selector:
matchLabels:
app: tea
template:
metadata:
labels:
app: tea
spec:
containers:
- name: tea
image: angiesoftware/angie-hello:plain-text
ports:
- containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
name: tea-svc
labels:
spec:
ports:
- port: 80
targetPort: 8080
protocol: TCP
name: http
selector:
app: tea
```
Примените настройки:
```console
$ kubectl create -f cafe.yaml
```
5. Создайте секрет с SSL-сертификатом:
### Пример
```yaml
apiVersion: v1
kind: Secret
metadata:
name: cafe-secret
type: kubernetes.io/tls
data:
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURMakNDQWhZQ0NRREFPRjl0THNhWFdqQU5CZ2txaGtpRzl3MEJBUXNGQURCYU1Rc3dDUVlEVlFRR0V3SlYKVXpFTE1Ba0dBMVVFQ0F3Q1EwRXhJVEFmQmdOVkJBb01HRWx1ZEdWeWJtVjBJRmRwWkdkcGRITWdVSFI1SUV4MApaREViTUJrR0ExVUVBd3dTWTJGbVpTNWxlR0Z0Y0d4bExtTnZiU0FnTUI0WERURTRNRGt4TWpFMk1UVXpOVm9YCkRUSXpNRGt4TVRFMk1UVXpOVm93V0RFTE1Ba0dBMVVFQmhNQ1ZWTXhDekFKQmdOVkJBZ01Ba05CTVNFd0h3WUQKVlFRS0RCaEpiblJsY201bGRDQlhhV1JuYVhSeklGQjBlU0JNZEdReEdUQVhCZ05WQkFNTUVHTmhabVV1WlhoaApiWEJzWlM1amIyMHdnZ0VpTUEwR0NTcUdTSWIzRFFFQkFRVUFBNElCRHdBd2dnRUtBb0lCQVFDcDZLbjdzeTgxCnAwanVKL2N5ayt2Q0FtbHNmanRGTTJtdVpOSzBLdGVjcUcyZmpXUWI1NXhRMVlGQTJYT1N3SEFZdlNkd0kyaloKcnVXOHFYWENMMnJiNENaQ0Z4d3BWRUNyY3hkam0zdGVWaVJYVnNZSW1tSkhQUFN5UWdwaW9iczl4N0RsTGM2SQpCQTBaalVPeWwwUHFHOVNKZXhNVjczV0lJYTVyRFZTRjJyNGtTa2JBajREY2o3TFhlRmxWWEgySTVYd1hDcHRDCm42N0pDZzQyZitrOHdnemNSVnA4WFprWldaVmp3cTlSVUtEWG1GQjJZeU4xWEVXZFowZXdSdUtZVUpsc202OTIKc2tPcktRajB2a29QbjQxRUUvK1RhVkVwcUxUUm9VWTNyemc3RGtkemZkQml6Rk8yZHNQTkZ4MkNXMGpYa05MdgpLbzI1Q1pyT2hYQUhBZ01CQUFFd0RRWUpLb1pJaHZjTkFRRUxCUUFEZ2dFQkFLSEZDY3lPalp2b0hzd1VCTWRMClJkSEliMzgzcFdGeW5acS9MdVVvdnNWQTU4QjBDZzdCRWZ5NXZXVlZycTVSSWt2NGxaODFOMjl4MjFkMUpINnIKalNuUXgrRFhDTy9USkVWNWxTQ1VwSUd6RVVZYVVQZ1J5anNNL05VZENKOHVIVmhaSitTNkZBK0NuT0Q5cm4yaQpaQmVQQ0k1ckh3RVh3bm5sOHl3aWozdnZRNXpISXV5QmdsV3IvUXl1aTlmalBwd1dVdlVtNG52NVNNRzl6Q1Y3ClBwdXd2dWF0cWpPMTIwOEJqZkUvY1pISWc4SHc5bXZXOXg5QytJUU1JTURFN2IvZzZPY0s3TEdUTHdsRnh2QTgKN1dqRWVxdW5heUlwaE1oS1JYVmYxTjM0OWVOOThFejM4Zk9USFRQYmRKakZBL1BjQytHeW1lK2lHdDVPUWRGaAp5UkU9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBcWVpcCs3TXZOYWRJN2lmM01wUHJ3Z0pwYkg0N1JUTnBybVRTdENyWG5LaHRuNDFrCkcrZWNVTldCUU5semtzQndHTDBuY0NObzJhN2x2S2wxd2k5cTIrQW1RaGNjS1ZSQXEzTVhZNXQ3WGxZa1YxYkcKQ0pwaVJ6ejBza0lLWXFHN1BjZXc1UzNPaUFRTkdZMURzcGRENmh2VWlYc1RGZTkxaUNHdWF3MVVoZHErSkVwRwp3SStBM0kreTEzaFpWVng5aU9WOEZ3cWJRcCt1eVFvT05uL3BQTUlNM0VWYWZGMlpHVm1WWThLdlVWQ2cxNWhRCmRtTWpkVnhGbldkSHNFYmltRkNaYkp1dmRySkRxeWtJOUw1S0Q1K05SQlAvazJsUkthaTAwYUZHTjY4NE93NUgKYzMzUVlzeFR0bmJEelJjZGdsdEkxNURTN3lxTnVRbWF6b1Z3QndJREFRQUJBb0lCQVFDUFNkU1luUXRTUHlxbApGZlZGcFRPc29PWVJoZjhzSStpYkZ4SU91UmF1V2VoaEp4ZG01Uk9ScEF6bUNMeUw1VmhqdEptZTIyM2dMcncyCk45OUVqVUtiL1ZPbVp1RHNCYzZvQ0Y2UU5SNThkejhjbk9SVGV3Y290c0pSMXBuMWhobG5SNUhxSkpCSmFzazEKWkVuVVFmY1hackw5NGxvOUpIM0UrVXFqbzFGRnM4eHhFOHdvUEJxalpzVjdwUlVaZ0MzTGh4bndMU0V4eUZvNApjeGI5U09HNU9tQUpvelN0Rm9RMkdKT2VzOHJKNXFmZHZ5dGdnOXhiTGFRTC94MGtwUTYyQm9GTUJEZHFPZVBXCktmUDV6WjYvMDcvdnBqNDh5QTFRMzJQem9idWJzQkxkM0tjbjMyamZtMUU3cHJ0V2wrSmVPRmlPem5CUUZKYk4KNHFQVlJ6NWhBb0dCQU50V3l4aE5DU0x1NFArWGdLeWNrbGpKNkY1NjY4Zk5qNUN6Z0ZScUowOXpuMFRsc05ybwpGVExaY3hEcW5SM0hQWU00MkpFUmgySi9xREZaeW5SUW8zY2czb2VpdlVkQlZHWTgrRkkxVzBxZHViL0w5K3l1CmVkT1pUUTVYbUdHcDZyNmpleHltY0ppbS9Pc0IzWm5ZT3BPcmxEN1NQbUJ2ek5MazRNRjZneGJYQW9HQkFNWk8KMHA2SGJCbWNQMHRqRlhmY0tFNzdJbUxtMHNBRzR1SG9VeDBlUGovMnFyblRuT0JCTkU0TXZnRHVUSnp5K2NhVQprOFJxbWRIQ2JIelRlNmZ6WXEvOWl0OHNaNzdLVk4xcWtiSWN1YytSVHhBOW5OaDFUanNSbmU3NFowajFGQ0xrCmhIY3FIMHJpN1BZU0tIVEU4RnZGQ3haWWRidUI4NENtWmlodnhicFJBb0dBSWJqcWFNWVBUWXVrbENkYTVTNzkKWVNGSjFKelplMUtqYS8vdER3MXpGY2dWQ0thMzFqQXdjaXowZi9sU1JxM0hTMUdHR21lemhQVlRpcUxmZVpxYwpSMGlLYmhnYk9jVlZrSkozSzB5QXlLd1BUdW14S0haNnpJbVpTMGMwYW0rUlk5WUdxNVQ3WXJ6cHpjZnZwaU9VCmZmZTNSeUZUN2NmQ21mb09oREN0enVrQ2dZQjMwb0xDMVJMRk9ycW40M3ZDUzUxemM1em9ZNDR1QnpzcHd3WU4KVHd2UC9FeFdNZjNWSnJEakJDSCtULzZzeXNlUGJKRUltbHpNK0l3eXRGcEFOZmlJWEV0LzQ4WGY2ME54OGdXTQp1SHl4Wlp4L05LdER3MFY4dlgxUE9ucTJBNWVpS2ErOGpSQVJZS0pMWU5kZkR1d29seHZHNmJaaGtQaS80RXRUCjNZMThzUUtCZ0h0S2JrKzdsTkpWZXN3WEU1Y1VHNkVEVXNEZS8yVWE3ZlhwN0ZjanFCRW9hcDFMU3crNlRYcDAKWmdybUtFOEFSek00NytFSkhVdmlpcS9udXBFMTVnMGtKVzNzeWhwVTl6WkxPN2x0QjBLSWtPOVpSY21Vam84UQpjcExsSE1BcWJMSjhXWUdKQ2toaVd4eWFsNmhZVHlXWTRjVmtDMHh0VGwvaFVFOUllTktvCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==
```
Примените настройки:
```console
$ kubectl create -f cafe-secret.yaml
```
6. Создайте Master-ресурс Ingress:
### Пример
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress-master
annotations:
angie.software/mergeable-ingress-type: "master"
spec:
ingressClassName: angie
tls:
- hosts:
- cafe.example.com
secretName: cafe-secret
rules:
- host: cafe.example.com
```
Примените настройки:
```console
$ kubectl create -f cafe-master.yaml
```
7. Создайте Minion-ресурсы Ingress:
### Пример coffee-minion
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress-coffee-minion
annotations:
angie.software/mergeable-ingress-type: "minion"
spec:
ingressClassName: angie
rules:
- host: cafe.example.com
http:
paths:
- path: /coffee
pathType: Prefix
backend:
service:
name: coffee-svc
port:
number: 80
```
### Пример tea-minion
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress-tea-minion
annotations:
angie.software/mergeable-ingress-type: "minion"
spec:
ingressClassName: angie
rules:
- host: cafe.example.com
http:
paths:
- path: /tea
pathType: Prefix
backend:
service:
name: tea-svc
port:
number: 80
```
Примените настройки:
```console
$ kubectl create -f coffee-minion.yaml
$ kubectl create -f tea-minion.yaml
```
8. Протестируйте конфигурацию.
Чтобы получить `coffee`:
```console
$ curl --resolve cafe.example.com:$IC_HTTPS_PORT:$IC_IP https://cafe.example.com:$IC_HTTPS_PORT/coffee --insecure
Server address: 10.12.0.18:80
Server name: coffee-7586895968-r26zn
```
Чтобы получить `tea`:
```console
$ curl --resolve cafe.example.com:$IC_HTTPS_PORT:$IC_IP https://cafe.example.com:$IC_HTTPS_PORT/tea --insecure
Server address: 10.12.0.19:80
Server name: tea-7cd44fcb4d-xfw2x
```
9. Просмотрите сгенерированную конфигурацию.
Для этого получите имя пода Ingress:
```console
$ kubectl get pods -n angie-ingress
NAME READY STATUS RESTARTS AGE
angie-ingress-66bc44674b-hrcx8 1/1 Running 0 4m
```
Посмотрите сгенерированную конфигурацию:
```console
$ kubectl exec -it angie-ingress-66bc44674b-hrcx8 -n angie-ingress -- cat /etc/angie/conf.d/default-cafe-ingress-master.conf
```
Пример содержимого:
```nginx
upstream default-cafe-ingress-coffee-minion-cafe.example.com-coffee-svc {
server 172.17.0.5:80;
server 172.17.0.6:80;
}
upstream default-cafe-ingress-tea-minion-cafe.example.com-tea-svc {
server 172.17.0.7:80;
server 172.17.0.8:80;
server 172.17.0.9:80;
}
server {
listen 80;
listen 443 ssl;
ssl_certificate /etc/angie/secrets/default-cafe-secret;
ssl_certificate_key /etc/angie/secrets/default-cafe-secret;
server_tokens on;
server_name cafe.example.com;
if ($scheme = http) {
return 301 https://$host:443$request_uri;
}
location /coffee {
proxy_http_version 1.1;
proxy_connect_timeout 60s;
proxy_read_timeout 60s;
client_max_body_size 1m;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering on;
proxy_pass http://default-cafe-ingress-coffee-minion-cafe.example.com-coffee-svc;
}
location /tea {
proxy_http_version 1.1;
proxy_connect_timeout 60s;
proxy_read_timeout 60s;
client_max_body_size 1m;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering on;
proxy_pass http://default-cafe-ingress-tea-minion-cafe.example.com-tea-svc;
}
}
```
# https://angie.software/anic/docs/ingress-resources/daemon-set.md
# Развертывание ANIC как DaemonSet
Вы можете развернуть ANIC как [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/).
Это позволяет запускать ANIC на всех или отдельно выбранных узлах кластера.
Инструкции по развертыванию смотрите в разделе [Установка с помощью манифестов](https://angie.software//anic/docs/installation/install.md#installation-daemonset).
# https://angie.software/anic/docs/ingress-resources/rewrites.md
# Поддержка переписывания (rewrites)
ANIC позволяет преобразовывать (переписывать) URI запроса перед отправкой в приложение.
Например, путь запроса `/tea/green` может быть перезаписан как `/green`.
Для настройки изменения URI для ресурса Ingress необходимо использовать аннотацию `angie.software/rewrite`.
Синтаксис:
```yaml
angie.software/rewrites: "serviceName=service1 rewrite=rewrite1[;serviceName=service2 rewrite=rewrite2;...]"
```
В следующем примере нагрузка между двумя приложениями, требующими изменения URI,
балансируется с помощью префиксного сопоставления:
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress
annotations:
angie.software/rewrites: "serviceName=tea-svc rewrite=/;serviceName=coffee-svc rewrite=/beans/"
spec:
rules:
- host: cafe.example.com
http:
paths:
- path: /tea/
pathType: Prefix
backend:
service:
name: tea-svc
port:
number: 80
- path: /coffee/
pathType: Prefix
backend:
service:
name: coffee-svc
port:
number: 80
```
Изменения URI для `tea-svc` (обратите внимание,
что запросы к `/tea` перенаправляются на `/tea/` с добавлением косой черты в конце):
| Исходный URI | Переписанный URI |
|----------------|--------------------|
| `/tea/` | `/` |
| `/tea/abc` | `/abc` |
Изменения URI для `coffee-svc`:
| Исходный URI | Переписанный URI |
|----------------|--------------------|
| `/coffee/` | `/beans/` |
| `/coffee/abc` | `/beans/abc` |
# https://angie.software/anic/docs/ingress-resources/session-persistence.md
# Сохранение сессий
Часто необходимо, чтобы запросы от клиента всегда передавались одному и тому же контейнеру бэкенда.
Вы можете включить такое поведение с помощью функции сохранения сессий, доступной в ANIC.
ANIC поддерживает метод `sticky cookie`.
При использовании этого метода ANIC добавляет session cookie в первый ответ от бэкенда,
идентифицируя контейнер, который отправил ответ.
Когда клиент делает следующий запрос, он отправляет значение `cookie`,
и ANIC направляет запрос в тот же контейнер.
Поддерживается также расширенный метод сохранения сессий: `sticky route`.
См. директиву [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) в конфигурации Angie.
## Синтаксис
Чтобы включить сохранение сессий для одного или нескольких сервисов,
добавьте аннотацию `angie.software/sticky-cookie-service` в определение ресурса Ingress.
В аннотации указываются сервисы, для которых нужно включить сохранение сессий,
а также различные параметры `cookie`.
```yaml
angie.software/sticky-cookie-services: "service1[;service2;...]"
```
Каждый сервис следует правилу ниже:
```console
serviceName=serviceName cookieName [expires=time] [domain=domain] [httponly] [secure] [path=path]
```
Синтаксис параметров такой же, как в директиве [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) в конфигурации Angie.
## Пример
В следующем примере включается сохранение сессий для двух сервисов:
`tea-svc` и `coffee-svc`:
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress-with-session-persistence
annotations:
angie.software/sticky-cookie-services: "serviceName=coffee-svc srv_id expires=1h path=/coffee;serviceName=tea-svc srv_id expires=2h path=/tea"
spec:
rules:
- host: cafe.example.com
http:
paths:
- path: /tea
pathType: Prefix
backend:
service:
name: tea-svc
port:
number: 80
- path: /coffee
pathType: Prefix
backend:
service:
name: coffee-svc
port:
number: 80
```
Для обоих сервисов sticky cookie имеет одинаковое имя `srv_id`.
Однако для каждого сервиса заданы разные значения времени жизни (`expires`) и пути (`path`).
Сохранение сессий продолжает работать даже в случае,
если запущено несколько реплик ANIC.
# https://angie.software/anic/docs/ingress-resources/custom-template.md
# Пользовательские шаблоны
ANIC использует шаблон для генерации конфигурации Angie для ресурсов Ingress.
Вы можете изменить этот шаблон и применить его с помощью ConfigMap.
См. пример [Пользовательские шаблоны](https://angie.software//anic/docs/shared-examples/custom-templates.md#custom-templates) в разделе "Общие примеры".
# https://angie.software/anic/docs/ingress-resources/grpc-services.md
# gRPC
Для поддержки gRPC-приложений в ANIC необходимо добавить аннотацию `angie.software/grpc-services` в определение ресурса Ingress.
Эта аннотация указывает, для каких сервисов нужно использовать gRPC.
#### NOTE
- Необходимо включить прослушиватель `HTTP/2` ( см. ключ `http2` в [ConfigMap](https://angie.software//anic/docs/configuration/configmap-resource.md#configmap-resource)).
- Ресурсы Ingress для gRPC-приложений должны включать терминацию TLS.
Синтаксис:
```yaml
angie.software/grpc-services: "service1[,service2,...]"
```
В примере ниже настроена балансировка нагрузки для трех приложений.
Одно из них использует gRPC.
Пример:
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: grpc-ingress
annotations:
angie.software/grpc-services: "grpc-svc"
spec:
ingressClassName: angie
tls:
- hosts:
- grpc.example.com
secretName: grpc-secret
rules:
- host: grpc.example.com
http:
paths:
- path: /helloworld.Greeter
pathType: Prefix
backend:
service:
name: grpc-svc
port:
number: 50051
- path: /tea
pathType: Prefix
backend:
service:
name: tea-svc
port:
number: 80
- path: /coffee
pathType: Prefix
backend:
service:
name: coffee-svc
port:
number: 80
```
В этом примере `grpc-svc` — это сервис для gRPC-приложения. Он будет доступен по пути `/helloworld.Greeter`.
# https://angie.software/anic/docs/ingress-resources/ssl-services.md
# SSL-сервисы
Для включения поддержки HTTPS и gRPC по SSL при подключении к эндпоинтам сервисов
необходимо использовать аннотацию `angie.software/ssl-services` в определение ресурса Ingress.
Эта аннотация указывает, для каких сервисов требуется использовать SSL-соединение.
Синтаксис:
```yaml
angie.software/ssl-services: "service1[,service2,...]"
```
В следующем примере настроена балансировка нагрузки для трех приложений.
Одно из них работает по HTTPS и требует SSL-подключения:
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress
annotations:
angie.software/ssl-services: "ssl-svc"
spec:
rules:
- host: cafe.example.com
http:
paths:
- path: /tea
pathType: Prefix
backend:
service:
name: tea-svc
port:
number: 80
- path: /coffee
pathType: Prefix
backend:
service:
name: coffee-svc
port:
number: 80
- path: /ssl
pathType: Prefix
backend:
service:
name: ssl-svc
port:
number: 443
```
В этом примере:
- Сервис `ssl-svc` — это приложение, доступное по HTTPS.
- Приложение доступно по пути `/ssl`.
- Для приложения задана аннотация `angie.software/ssl-services: "ssl-svc"`, указывающая,
что соединения с этим сервисом должны осуществляться через SSL.
# https://angie.software/anic/docs/ingress-resources/tcp-udp.md
# TCP- и UDP-балансировка для DNS
В этом примере разворачивается ANIC и DNS-сервер, а затем настраивается балансировка TCP и UDP
для DNS-сервиса с использованием ключа `stream-snippets` в ConfigMap.
Стандартные ресурсы Ingress в Kubernetes предполагают, что используется HTTP-трафик,
и не предназначены для обработки TCP- или UDP-трафика, поэтому,
чтобы встроить необходимую конфигурацию балансировки TCP/UDP в блок `stream {}`,
используется ключ `stream-snippets` из ConfigMap.
В ANIC можно использовать headless-сервис и его DNS-имя,
чтобы получить реальные IP-адреса подов и балансировать нагрузку между ними.
ANIC регулярно заново разрешает DNS-имя, чтобы автоматически обновлять его
при добавлении или удалении подов.
#### NOTE
- Для тестирования используется утилита **dig**. Убедитесь, что она установлена.
- Для настройки TCP/UDP-балансировки используется родная конфигурация Angie.
1. Установите ANIC. Убедитесь, что порт 5353 открыт как для TCP-, так и для UDP-трафика.
2. Сохраните публичный IP-адрес ANIC в переменной оболочки:
```console
$ IC_IP=<ваш_IP-адрес>
```
3. Сохраните порт 5353, используемый ANIC, в переменной оболочки:
```console
$ IC_5353_PORT=<номер порта>
```
#### NOTE
Если вы хотите настроить ANIC с помощью сервиса `LoadBalancer`, то в нем нельзя использовать
протоколы TCP и UDP одновременно.
В этом случае создайте два отдельных сервиса: для TCP и для UDP.
Соответственно, у вас будет два разных публичных IP-адреса (см. примеры ниже).
4. Разверните DNS-сервер:
- Разверните две реплики `CoreDNS`, настроенные на пересылку DNS-запросов на `8.8.8.8`.
- Создайте два сервиса — `coredns` и `coredns-headless`.
### Пример
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: coredns
data:
Corefile: |
.:53 {
forward . 8.8.8.8:53
log
}
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: coredns
spec:
replicas: 2
selector:
matchLabels:
app: coredns
template:
metadata:
labels:
app: coredns
spec:
containers:
- name: coredns
image: coredns/coredns:1.10.0
args: [ "-conf", "/etc/coredns/Corefile" ]
volumeMounts:
- name: config-volume
mountPath: /etc/coredns
readOnly: true
ports:
- containerPort: 53
name: dns
protocol: UDP
- containerPort: 53
name: dns-tcp
protocol: TCP
securityContext:
allowPrivilegeEscalation: false
capabilities:
add:
- NET_BIND_SERVICE
drop:
- all
readOnlyRootFilesystem: true
volumes:
- name: config-volume
configMap:
name: coredns
items:
- key: Corefile
path: Corefile
---
apiVersion: v1
kind: Service
metadata:
name: coredns
spec:
selector:
app: coredns
ports:
- name: dns
port: 53
protocol: UDP
- name: dns-tcp
port: 53
protocol: TCP
---
apiVersion: v1
kind: Service
metadata:
name: coredns-headless
spec:
clusterIP: None
selector:
app: coredns
ports:
- name: dns
port: 53
protocol: UDP
- name: dns-tcp
port: 53
protocol: TCP
```
Примените настройки:
```console
$ kubectl apply -f dns.yaml
```
5. Создайте конфигурацию балансировки нагрузки. В примере настраиваются два сервера:
один принимает TCP-трафик на порту 5353, а второй — UDP-трафик на том же порту.
Оба сервера балансируют входящий трафик между подами CoreDNS.
### Пример
```yaml
kind: ConfigMap
apiVersion: v1
metadata:
name: angie-config
namespace: angie-ingress
data:
stream-snippets: |
resolver kube-dns.kube-system.svc.cluster.local valid=5s;
upstream coredns-udp {
zone coredns-udp 64k;
server coredns-headless.default.svc.cluster.local service=_dns._udp resolve;
}
server {
listen 5353 udp;
listen [::]:5353 udp;
proxy_pass coredns-udp;
proxy_responses 1;
status_zone coredns-udp;
}
upstream coredns-tcp {
zone coredns-tcp 64k;
server coredns-headless.default.svc.cluster.local service=_dns-tcp._tcp resolve;
}
server {
listen 5353;
listen [::]:5353;
proxy_pass coredns-tcp;
status_zone coredns-tcp;
}
```
ANIC поддерживает повторное разрешение DNS-имен с помощью параметра `resolve` в директиве `upstream`.
При использовании параметра `resolve`, ANIC не завершит перезагрузку с ошибкой,
если имя upstream-хоста не удается разрешить.
Помимо IP-адресов, ANIC также может получать порты через DNS-записи типа SRV.
Для разрешения IP-адресов и портов ANIC использует Kube-DNS, который указывается в директиве `resolver`.
Также устанавливается параметр `valid=5s`, чтобы ANIC повторно разрешал DNS-имена каждые 5 секунд.
Вместо обычного сервиса `coredns` используется `coredns-headless`.
Этот сервис создается как headless-сервис, то есть ему не выделяется виртуальный IP,
и ANIC может разрешить все реальные IP-адреса подов CoreDNS.
#### NOTE
ANIC завершит перезагрузку с ошибкой, если DNS-имя, указанное в директиве `resolver`, не может быть разрешено.
Чтобы избежать этого, рекомендуется использовать виртуальный IP-адрес сервиса kube-dns вместо его DNS-имени.
6. Обновите ConfigMap, добавив ключ `stream-snippets` с конфигурацией балансировки нагрузки.
Используется ключ `stream-snippets` в объекте ConfigMap,
чтобы настроить балансировку TCP- и UDP-трафика для наших подов CoreDNS.
Примените настройки:
```console
$ kubectl apply -f angie-config.yaml
```
7. Проверьте, что конфигурация успешно применена:
```console
$ kubectl describe configmap angie-config -n angie-ingress
. . .
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Updated 3s ANIC Configuration from angie-ingress/angie-config was updated
```
8. Протестируйте DNS-сервер.
Чтобы проверить, что балансировка TCP/UDP работает, выполните разрешение имени `kubernetes.io`
с использованием нашего DNS-сервера, доступного через ANIC.
Разрешение `kubernetes.io` через UDP:
```shell
$ dig @$IC_IP -p $IC_5353_PORT kubernetes.io
; <<>> DiG 9.10.6 <<>> @> -p 5353 kubernetes.io
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 33368
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 512
;; QUESTION SECTION:
;kubernetes.io. IN A
;; ANSWER SECTION:
kubernetes.io. 299 IN A 45.54.44.100
;; Query time: 111 msec
;; SERVER:#5353()
;; WHEN: Fri Aug 17 12:49:54 BST 2018
;; MSG SIZE rcvd: 71
```
Разрешение `kubernetes.io` через TCP:
```shell
$ dig @$IC_IP -p $IC_5353_PORT kubernetes.io +tcp
; <<>> DiG 9.10.6 <<>> @ -p 5353 kubernetes.io +tcp
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 49032
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 512
;; QUESTION SECTION:
;kubernetes.io. IN A
;; ANSWER SECTION:
kubernetes.io. 146 IN A 45.54.44.100
;; Query time: 95 msec
;; SERVER: #5353()
;; WHEN: Fri Aug 17 12:52:25 BST 2018
;; MSG SIZE rcvd: 71
Look at the Ingress Controller logs:
$ kubectl logs -n angie-ingress
. . .
[17/Aug/2018:11:49:54 +0000] UDP 200 71 42 0.016
[17/Aug/2018:11:52:25 +0000] TCP 200 73 44 0.098
```
Посмотрите логи:
```shell
$ kubectl logs -n angie-ingress
. . .
[17/Aug/2018:11:49:54 +0000] UDP 200 71 42 0.016
[17/Aug/2018:11:52:25 +0000] TCP 200 73 44 0.098
```
# https://angie.software/anic/docs/ingress-resources/websocket.md
# WebSocket
Для балансировки нагрузки на приложение, использующее WebSocket,
необходимо использовать аннотацию `angie.software/websocket-services`.
Эта аннотация используется в ресурсе Ingress и указывает,
какие сервисы работают с использованием WebSocket.
Синтаксис:
```yaml
angie.software/websocket-services: "service1[,service2,...]"
```
Пример:
В следующем примере настраивается балансировка нагрузки для трех приложений.
Одно из них, `ws-svc`, использует WebSocket и становится доступным по пути `/ws`.
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cafe-ingress
annotations:
angie.software/websocket-services: "ws-svc"
spec:
rules:
- host: cafe.example.com
http:
paths:
- path: /tea
pathType: Prefix
backend:
service:
name: tea-svc
port:
number: 80
- path: /coffee
pathType: Prefix
backend:
service:
name: coffee-svc
port:
number: 80
- path: /ws
pathType: Prefix
backend:
service:
name: ws-svc
port:
number: 8008
```
# https://angie.software/anic/docs/shared-examples.md
# Общие примеры
В этом разделе собраны примеры настройки и типовые конфигурации для общих примеров.
[Пользовательские шаблоны](https://angie.software//anic/docs/shared-examples/custom-templates.md#custom-templates)
[Пользовательский формат журнала (log-format)](https://angie.software//anic/docs/shared-examples/custom-log-format.md#custom-log-format)
[Протокол PROXY](https://angie.software//anic/docs/shared-examples/proxy-protocol.md#proxy-protocol)
[Wildcard-сертификат](https://angie.software//anic/docs/shared-examples/wildcard-tls-certificate.md#wildcard-tls-certificate)
[Пример default-server-secret](https://angie.software//anic/docs/shared-examples/default-server-secret.md#default-server-secret)
# https://angie.software/anic/docs/shared-examples/custom-templates.md
# Пользовательские шаблоны
Для изменения конфигурации Angie для ресурсов Ingress,
ресурсов VirtualServer и основного файла конфигурации Angie можно использовать пользовательские шаблоны.
Пользовательские шаблоны ANIC настраиваются через [ConfigMap](https://angie.software//anic/docs/configuration/configmap-resource.md#configmap-resource) с помощью следующих ключей:
- `main-template` — задает основной шаблон конфигурации Angie.
- `ingress-template` — задает шаблон конфигурации ANIC для ресурса Ingress.
- `virtualserver-template` — задает шаблон конфигурации ANIC для ресурса VirtualServer.
## Пример
```yaml
kind: ConfigMap
apiVersion: v1
metadata:
name: angie-config
namespace: angie-ingress
data:
main-template: |
worker_processes {{.WorkerProcesses}};
...
include /etc/angie/conf.d/*.conf;
}
ingress-template: |
{{range $upstream := .Upstreams}}
upstream {{$upstream.Name}} {
{{if $upstream.LBMethod }}{{$upstream.LBMethod}};{{end}}
...
}{{end}}
virtualserver-template: |
{{ range $u := .Upstreams }}
upstream {{ $u.Name }} {
{{ if ne $u.UpstreamZoneSize "0" }}zone {{ $u.Name }} {{ $u.UpstreamZoneSize }};{{ end }}
...
}
{{ end }}
```
#### NOTE
- Шаблоны в примере обрезаны для краткости.
- Основные шаблоны `angie.tmpl` и `angie.ingress.tmpl`
находятся по пути `internal/configs/version1`.
Шаблон VirtualServer (`angie.virtualserver.tmpl`) расположен по пути `internal/configs/version2`.
## Диагностика ошибок
- Если пользовательский шаблон содержит ошибку, ANIC не запустится.
Ошибка отобразится в журнале.
Пример ошибки:
```none
Error updating Angie main template: template: angieTemplate:98: unexpected EOF
```
- Если некорректный пользовательский шаблон был добавлен после запуска ANIC,
конфигурация не обновится. Ошибка отобразится в журнале, в событии, связанном с ConfigMap.
Пример ошибки:
```none
Error when updating config from ConfigMap: Invalid angie configuration detected, not reloading
```
События ConfigMap можно просмотреть с помощью команды `kubectl describe -n anic configmap angie-config`.
Пример события с ошибкой:
```none
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Updated 12s (x2 over 25s) anic Configuration from anic/angie-config was updated
Warning UpdatedWithError 10s anic Configuration from anic/angie-config was updated, but not applied: Error when parsing the main template: template: angieTemplate:98: unexpected EOF
Warning UpdatedWithError 8s anic Configuration from anic/angie-config was updated, but not applied: Error when writing main Config
```
# https://angie.software/anic/docs/shared-examples/custom-log-format.md
# Пользовательский формат журнала
Вы можете настроить пользовательский [формат журнала (log-format)](https://angie.software//angie/docs/configuration/modules/http/http_log.md#log-format) с помощью ресурса ConfigMap:
```yaml
kind: ConfigMap
apiVersion: v1
metadata:
name: angie-config
namespace: angie-ingress
data:
log-format: '$remote_addr - $remote_user [$time_local] "$request" $status $grpc_status $body_bytes_sent "$http_referer" "$http_user_agent" "$http_x_forwarded_for" "$resource_name" "$resource_type" "$resource_namespace" "$service"'
```
В дополнение к [встроенным переменным Angie](https://angie.software//angie/docs/configuration/varindex.md#varindex) можно использовать переменные, которые настраиваются в ANIC:
- `$resource_type` — тип ресурса Kubernetes, который обработал запрос клиента.
- `$resource_name` — имя ресурса Kubernetes, который обработал запрос клиента.
- `$resource_namespace` — пространство имен (namespace), в котором находится ресурс.
- `$service` — имя сервиса, на который был направлен клиентский запрос.
- `$grpc_status` — код статуса gRPC (при нормальной работе берется из трейлера HTTP/2 (`grpc_status`), возвращаемого бэкендом, при некоторых ошибках — из заголовка HTTP/2 (`grpc_status`), установленного бэкендом или Angie).
#### NOTE
Эти переменные доступны только для ресурсов Ingress, VirtualServer и VirtualServerRoute.
# https://angie.software/anic/docs/shared-examples/proxy-protocol.md
# Протокол PROXY
Прокси-серверы и балансировщики нагрузки (например HAProxy или AWS ELB) могут передавать
информацию о клиенте (IP-адрес и порт) следующему прокси или балансировщику с помощью протокола PROXY.
Чтобы ANIC мог получить эту информацию, в ресурсе ConfigMap необходимо задать следующие параметры:
- `proxy-protocol` — должен быть установлен в значение `True`;
- `real-ip-header` — должен быть установлен в значение `proxy_protocol`;
- `set-real-ip-from` — IP-адрес или подсеть прокси или балансировщика, откуда будет приходить информация
(подробнее см. [set_real_ip_from](https://angie.software//angie/docs/configuration/modules/http/http_realip.md#set-real-ip-from)).
#### NOTE
Протокол PROXY будет применяться ко всем ресурсам Ingress и VirtualServer.
Ресурс TransportServer поддерживает протокол PROXY только при включенном `TLS Passthrough`.
## Пример конфигурации
```yaml
kind: ConfigMap
apiVersion: v1
metadata:
name: angie-config
data:
proxy-protocol: "True"
real-ip-header: "proxy_protocol"
set-real-ip-from: "192.168.0.0/16"
```
В приведенном примере протокол PROXY настраивается через ресурс ConfigMap.
Параметр `set-real-ip-from` установлен в `192.168.0.0/16` — это CIDR-подсеть прокси,
стоящего перед ANIC в этом примере. Если вы хотите доверять всем IP-адресам, можно задать значение `0.0.0.0/0`.
После создания ресурса ConfigMap IP-адрес клиента будет доступен через переменную `$remote_addr` в конфигурации Angie.
По умолчанию ANIC запоминает значение `$remote_addr` и передает его бэкенду в заголовке X-Real-IP.
Стандартный формат журнала Angie по умолчанию:
`'$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"'`.
# https://angie.software/anic/docs/shared-examples/wildcard-tls-certificate.md
# Wildcard-сертификат
Wildcard-сертификат упрощает настройку терминации TLS,
если необходимо использовать один и тот же TLS-сертификат
в нескольких ресурсах Ingress и VirtualServer в разных пространствах имен.
Wildcard-сертификат позволяет централизованно управлять TLS-сертификатами для множества доменов
без дублирования секрета в каждом ресурсе.
Обычно такой сертификат выдается для поддомена (например, `*.example.com`),
а хосты ресурсов Ingress и VirtualServer включают этот поддомен (например `foo.example.com`, `bar.example.com`).
#### IMPORTANT
Предварительно необходимо запустить ANIC с аргументом командной строки `-wildcard-tls-secret`
со значением TLS-секрета, содержащего wildcard-сертификат и ключ.
ANIC поддерживает только один wildcard-секрет.
```console
-wildcard-tls-secret=angie-ingress/wildcard-tls-secret
```
## Пример
В примерах ниже показана настройка терминации TLS для ресурса Ingress с хостом `foo.example.com` и ресурса VirtualServer с хостом `bar.example.com`.
Пример для Ingress из пространства имен `foo`:
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: foo
namespace: foo
spec:
ingressClassName: angie
tls:
- hosts:
- foo.example.com
rules:
- host: foo.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: foo-service
port:
number: 80
```
Пример для VirtualServer из пространства имен `bar`:
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
name: bar
namespace: bar
spec:
host: bar.example.com
tls:
secret: ""
upstreams:
- name: bar
service: bar-service
port: 80
routes:
- path: /
action:
pass: bar
```
В примерах выше конкретный TLS-секрет не указан:
- в ресурсе Ingress отсутствует поле `secret` в блоке `tls`;
- в ресурсе VirtualServer поле `secret` пустое (`""`).
В этом случае будет использоваться wildcard-секрет,
указанный с помощью параметра `-wildcard-tls-secret` при запуске ANIC.
# https://angie.software/anic/docs/shared-examples/default-server-secret.md
# Пример default-server-secret
Ниже приведен пример `default-server-secret`:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: default-server-secret
namespace: angie-ingress
type: kubernetes.io/tls
data:
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUN2akNDQWFZQ0NRREFPRjl0THNhWFhEQU5CZ2txaGtpRzl3MEJBUXNGQURBaE1SOHdIUVlEVlFRRERCWk8KUjBsT1dFbHVaM0psYzNORGIyNTBjbTlzYkdWeU1CNFhEVEU0TURreE1qRTRNRE16TlZvWERUSXpNRGt4TVRFNApNRE16TlZvd0lURWZNQjBHQTFVRUF3d1dUa2RKVGxoSmJtZHlaWE56UTI5dWRISnZiR3hsY2pDQ0FTSXdEUVlKCktvWklodmNOQVFFQkJRQURnZ0VQQURDQ0FRb0NnZ0VCQUwvN2hIUEtFWGRMdjNyaUM3QlBrMTNpWkt5eTlyQ08KR2xZUXYyK2EzUDF0azIrS3YwVGF5aGRCbDRrcnNUcTZzZm8vWUk1Y2Vhbkw4WGM3U1pyQkVRYm9EN2REbWs1Qgo4eDZLS2xHWU5IWlg0Rm5UZ0VPaStlM2ptTFFxRlBSY1kzVnNPazFFeUZBL0JnWlJVbkNHZUtGeERSN0tQdGhyCmtqSXVuektURXUyaDU4Tlp0S21ScUJHdDEwcTNRYzhZT3ExM2FnbmovUWRjc0ZYYTJnMjB1K1lYZDdoZ3krZksKWk4vVUkxQUQ0YzZyM1lma1ZWUmVHd1lxQVp1WXN2V0RKbW1GNWRwdEMzN011cDBPRUxVTExSakZJOTZXNXIwSAo1TmdPc25NWFJNV1hYVlpiNWRxT3R0SmRtS3FhZ25TZ1JQQVpQN2MwQjFQU2FqYzZjNGZRVXpNQ0F3RUFBVEFOCkJna3Foa2lHOXcwQkFRc0ZBQU9DQVFFQWpLb2tRdGRPcEsrTzhibWVPc3lySmdJSXJycVFVY2ZOUitjb0hZVUoKdGhrYnhITFMzR3VBTWI5dm15VExPY2xxeC9aYzJPblEwMEJCLzlTb0swcitFZ1U2UlVrRWtWcitTTFA3NTdUWgozZWI4dmdPdEduMS9ienM3bzNBaS9kclkrcUI5Q2k1S3lPc3FHTG1US2xFaUtOYkcyR1ZyTWxjS0ZYQU80YTY3Cklnc1hzYktNbTQwV1U3cG9mcGltU1ZmaXFSdkV5YmN3N0NYODF6cFErUyt1eHRYK2VBZ3V0NHh3VlI5d2IyVXYKelhuZk9HbWhWNThDd1dIQnNKa0kxNXhaa2VUWXdSN0diaEFMSkZUUkk3dkhvQXprTWIzbjAxQjQyWjNrN3RXNQpJUDFmTlpIOFUvOWxiUHNoT21FRFZkdjF5ZytVRVJxbStGSis2R0oxeFJGcGZnPT0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=
tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFcEFJQkFBS0NBUUVBdi91RWM4b1JkMHUvZXVJTHNFK1RYZUprckxMMnNJNGFWaEMvYjVyYy9XMlRiNHEvClJOcktGMEdYaVN1eE9ycXgrajlnamx4NXFjdnhkenRKbXNFUkJ1Z1B0ME9hVGtIekhvb3FVWmcwZGxmZ1dkT0EKUTZMNTdlT1l0Q29VOUZ4amRXdzZUVVRJVUQ4R0JsRlNjSVo0b1hFTkhzbysyR3VTTWk2Zk1wTVM3YUhudzFtMApxWkdvRWEzWFNyZEJ6eGc2clhkcUNlUDlCMXl3VmRyYURiUzc1aGQzdUdETDU4cGszOVFqVUFQaHpxdmRoK1JWClZGNGJCaW9CbTVpeTlZTW1hWVhsMm0wTGZzeTZuUTRRdFFzdEdNVWozcGJtdlFmazJBNnljeGRFeFpkZFZsdmwKMm82MjBsMllxcHFDZEtCRThCay90elFIVTlKcU56cHpoOUJUTXdJREFRQUJBb0lCQVFDZklHbXowOHhRVmorNwpLZnZJUXQwQ0YzR2MxNld6eDhVNml4MHg4Mm15d1kxUUNlL3BzWE9LZlRxT1h1SENyUlp5TnUvZ2IvUUQ4bUFOCmxOMjRZTWl0TWRJODg5TEZoTkp3QU5OODJDeTczckM5bzVvUDlkazAvYzRIbjAzSkVYNzZ5QjgzQm9rR1FvYksKMjhMNk0rdHUzUmFqNjd6Vmc2d2szaEhrU0pXSzBwV1YrSjdrUkRWYmhDYUZhNk5nMUZNRWxhTlozVDhhUUtyQgpDUDNDeEFTdjYxWTk5TEI4KzNXWVFIK3NYaTVGM01pYVNBZ1BkQUk3WEh1dXFET1lvMU5PL0JoSGt1aVg2QnRtCnorNTZud2pZMy8yUytSRmNBc3JMTnIwMDJZZi9oY0IraVlDNzVWYmcydVd6WTY3TWdOTGQ5VW9RU3BDRkYrVm4KM0cyUnhybnhBb0dCQU40U3M0ZVlPU2huMVpQQjdhTUZsY0k2RHR2S2ErTGZTTXFyY2pOZjJlSEpZNnhubmxKdgpGenpGL2RiVWVTbWxSekR0WkdlcXZXaHFISy9iTjIyeWJhOU1WMDlRQ0JFTk5jNmtWajJTVHpUWkJVbEx4QzYrCk93Z0wyZHhKendWelU0VC84ajdHalRUN05BZVpFS2FvRHFyRG5BYWkyaW5oZU1JVWZHRXFGKzJyQW9HQkFOMVAKK0tZL0lsS3RWRzRKSklQNzBjUis3RmpyeXJpY05iWCtQVzUvOXFHaWxnY2grZ3l4b25BWlBpd2NpeDN3QVpGdwpaZC96ZFB2aTBkWEppc1BSZjRMazg5b2pCUmpiRmRmc2l5UmJYbyt3TFU4NUhRU2NGMnN5aUFPaTVBRHdVU0FkCm45YWFweUNweEFkREtERHdObit3ZFhtaTZ0OHRpSFRkK3RoVDhkaVpBb0dCQUt6Wis1bG9OOTBtYlF4VVh5YUwKMjFSUm9tMGJjcndsTmVCaWNFSmlzaEhYa2xpSVVxZ3hSZklNM2hhUVRUcklKZENFaHFsV01aV0xPb2I2NTNyZgo3aFlMSXM1ZUtka3o0aFRVdnpldm9TMHVXcm9CV2xOVHlGanIrSWhKZnZUc0hpOGdsU3FkbXgySkJhZUFVWUNXCndNdlQ4NmNLclNyNkQrZG8wS05FZzFsL0FvR0FlMkFVdHVFbFNqLzBmRzgrV3hHc1RFV1JqclRNUzRSUjhRWXQKeXdjdFA4aDZxTGxKUTRCWGxQU05rMXZLTmtOUkxIb2pZT2pCQTViYjhibXNVU1BlV09NNENoaFJ4QnlHbmR2eAphYkJDRkFwY0IvbEg4d1R0alVZYlN5T294ZGt5OEp0ek90ajJhS0FiZHd6NlArWDZDODhjZmxYVFo5MWpYL3RMCjF3TmRKS2tDZ1lCbyt0UzB5TzJ2SWFmK2UwSkN5TGhzVDQ5cTN3Zis2QWVqWGx2WDJ1VnRYejN5QTZnbXo5aCsKcDNlK2JMRUxwb3B0WFhNdUFRR0xhUkcrYlNNcjR5dERYbE5ZSndUeThXczNKY3dlSTdqZVp2b0ZpbmNvVlVIMwphdmxoTUVCRGYxSjltSDB5cDBwWUNaS2ROdHNvZEZtQktzVEtQMjJhTmtsVVhCS3gyZzR6cFE9PQotLS0tLUVORCBSU0EgUFJJVkFURSBLRVktLS0tLQo=
```
# https://angie.software/anic/docs/known-issues-and-solutions.md
# Известные проблемы и решения
## Ошибка `"proxy_busy_buffers_size" must be less than the size of all "proxy_buffers" minus one buffer`
Сообщение указывает на ошибку в конфигурации из-за неправильного соотношения значений параметров `proxy_buffer_size` и `proxy_buffers`.
| Параметр | Описание | Значение по умолчанию |
|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|
| `proxy_buffer_size` | Задает размер основного буфера для обработки данных. Значение `proxy_buffer_size` может быть не более чем в два раза больше размера `proxy_buffers`. | `4k | 8k` |
| `proxy-buffers` | Задает количество и размер дополнительных буферов. При значении `8 8k` общий размер будет равен `8 × 8 = 64k`. | `8 4k | 8k` |
| `proxy_busy_buffers_size` | Ограничивает суммарный размер буферов, которые могут быть заняты для отправки ответа.
Значение должно быть меньше, чем общий размер всех `proxy_buffers` минус размер одного буфера.
Если значение `proxy-buffers` равно `8 8k`, то значение `proxy_busy_buffers_size`
должно быть меньше, чем `8 × 8 - 8`, т.е. меньше `56k`. | `8k | 16k` |
Ошибка может возникнуть, если значение `proxy_buffer_size` было изменено с помощью аннотации на большее и, таким образом, было нарушено соотношение параметров. Для решения проблемы необходимо с помощью аннотации установить размер для `proxy_buffers`.
Например:
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
angie.software/proxy-buffers: '8 32k'
angie.software/proxy-buffer-size: '64k'
name: test-echo
namespace: echoserver
spec:
ingressClassName: angie
rules:
- host: test.example.com
http:
paths:
- backend:
service:
name: echoserver
port:
number: 8077
pathType: ImplementationSpecific
```
# https://angie.software/anic/docs/changes.md
# Версии Angie Ingress Controller (ANIC)
## 2026
### ANIC 0.7.5
Дата выпуска: 02.06.2026
#### Безопасность
- Версия Angie PRO обновлена до [1.11.6](https://angie.software//angie/docs/pro_changes.md#angie-pro-1-11-6);
- Обновлена версия Go.
### ANIC 0.7.4
Дата выпуска: 20.05.2026
#### Безопасность
- Версия Angie PRO обновлена до [1.11.5](https://angie.software//angie/docs/pro_changes.md#angie-pro-1-11-5);
- Обновлена версия Go;
- Обновлены сторонние библиотеки и зависимости.
## 2025
### ANIC 0.7.3
Дата выпуска: 26.12.2025
#### Безопасность
Исправление уязвимостей.
### ANIC 0.7.2
Дата выпуска: 03.10.2025
#### Исправления
Исправлено поведение аннотации `path-regex`.
### ANIC 0.7.1
Дата выпуска: 03.06.2025
#### Добавления
- Версия Angie PRO обновлена до [1.9.1](https://angie.software//angie/docs/pro_changes.md#pro-changes).
- В справку добавлен раздел [Общие примеры](https://angie.software//anic/docs/shared-examples/index.md#shared-examples).
#### Исправления
Исправление уязвимостей.
### ANIC 0.7.0
Дата выпуска: 05.02.2025.
#### Добавления
Установка ANIC [по лицензии](https://angie.software//anic/docs/installation/licensing.md#licensing).
## 2024
### ANIC 0.6.0
Дата выпуска: 26.12.2024.
#### Добавления
Новые функции и настройки:
- Добавлены дополнительные поля в метриках Prometheus для ANIC:
- `controller_pod`
- `controller_namespace`
- `controller_class`
- Добавлена возможность настраивать и осуществлять авторизацию клиента [на основании результатов подзапроса](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserverroute-authrequestlocations).
- Версия Angie PRO обновлена до `1.8.1`.
### ANIC 0.5.0
Дата выпуска: 30.09.2024.
#### Добавления
Новые функции и настройки:
- Добавлена возможность настраивать [OIDC-авторизацию](https://angie.software//anic/docs/configuration/policy-resource.md#oidc-policy).
- Появилась возможность настройки [JWT-авторизацию](https://angie.software//anic/docs/configuration/policy-resource.md#oidc-policy).
- Добавлена аннотация `angie.software/configmap` с параметром `namespace/config-name`, которая позволяет определить [расширенный ConfigMap](https://angie.software//anic/docs/configuration/configmap-resource.md#annotation-configmap) для заданного Ingress-ресурса.
- Директива [staticLocations](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#staticlocations) позволяет задавать расположение для раздачи статических файлов.
- Параметр [angie-status-prometheus-path](https://angie.software//anic/docs/configuration/command-line-arguments.md#angie-status-prometheus-path) позволяет менять путь для статистики Angie в формате Prometheus.
- Добавлены параметры [настройки SSL](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#virtualservertls) для ресурса VirtualServer:
- `ssl_session_timeout`
- `ssl_session_cache`
- `ssl_session_tickets`
- `ssl_stapling`
- `ssl_stapling_verify`
- Для директивы [ssl_prefer_server_ciphers](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-prefer-server-ciphers) теперь можно задавать значение `off`.
- Появилась возможность добавлять директиву [map](https://angie.software//angie/docs/configuration/modules/stream/stream_map.md#s-map) в конфигурацию Angie
PRO, см. [примеры настройки](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserver-maps).
- Появилась поддержка директивы [activeHealthProbes](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#activehealthprobes) в Angie PRO.
- Версия Angie PRO обновлена до `1.7.0`.
Для облегчения процесса миграции сделаны следующие улучшения:
- Параметры типа `boolean` теперь могут принимать значения `true` или `false`, `t` или `f`, `on` или `off` и `1` или `0`.
- Параметр `proxy-buffers` директивы [Upstream.buffers](https://angie.software//anic/docs/configuration/virtualserver-and-virtualserverroute-resources.md#upstreambuffers) теперь может принимать только значение количества буферов `number`, без указания размера `size`. Если значение `size` не указано, то по умолчанию будет задано `8K`.
#### Исправления
- Исправлена ошибка при указании значения `HTTPS` для `backend-protocol`.
- Исправлено отображение IP в статусе `k8s`.
- Параметр `include-year` больше нельзя изменять, его значение теперь всегда `true`.
### ANIC 0.4.0
Дата выпуска: 04.06.2024.
#### Добавления
Новые функции и настройки:
- Добавлены алиасы для следующих аннотаций:
- `angie.software/force-ssl-redirect` — перенаправляет HTTP-запросы на HTTPS.
- `angie.software/proxy-body-size` — устанавливает максимальный размер для тела запроса, которое может обработать проксируемый сервер.
- `angie.software/proxy-buffer-size` — определяет размер буфера для чтения заголовков ответов от проксируемого сервера.
- `angie.software/proxy-buffering` — включает или отключает [буферизацию ответов](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-buffering) от проксируемого сервера.
- `angie.software/proxy-buffers` — определяет количество буферов, используемых для хранения ответа от проксируемого сервера.
- `angie.software/proxy-max-temp-file-size` — задает максимальный размер временного файла, используемого для буферизации больших ответов.
- Директива [server_tokens](https://angie.software//angie/docs/configuration/modules/http/index.md#server-tokens) теперь может принимать строковые значения.
- Версия Angie PRO обновлена до `1.5.2`.
#### Исправления
- Исправлены требования к `resolver-addresses`.
### ANIC 0.3.0
Дата выпуска: 02.03.2024.
#### Добавления
Новые функции и настройки:
- Добавлена аннотация `angie.software/force-ssl-redirect`, с помощью которой можно переводить небезопасные HTTP-запросы на защищенные HTTPS, что позволит исправить возможные ошибки при использовании SSL.
#### NOTE
В связи с особенностями работы аннотации `force-ssl-redirect` рекомендуем
использовать альтернативную настройку — `backend-protocol` со значением `HTTPS`.
- В Helm-чарты добавлены CRD (Common Resource Definitions), такие как Virtual Server, Virtual Server Route,TransportServer, Policies. Теперь пользователи Helm могут использовать эти определения в своих проектах, что значительно расширяет возможности настройки веб-сервера по сравнению со стандартным ресурсом Ingress.
#### Исправления
- Теперь ANIC запускается от имени пользователя `angie`.
## 2023
### ANIC 0.2.0
Дата выпуска: 23.11.2023.
#### Добавления
- Добавлена поддержка консоли [Console Light](https://angie.software//angie/docs/configuration/monitoring.md#monitoring) для мониторинга активности в реальном времени.
- Теперь можно отключать протокол `ipv6` с помощью [-disable-ipv6](https://angie.software//anic/docs/configuration/command-line-arguments.md#disable-ipv6).
- Добавлена точка подключения Prometheus `/ps8` для мониторинга статуса.
- Добавлена поддержка `sticky cookie` и `sticky route`.
- В параметры конфига добавлена переменная `$proxy_upstream_name` для использования в формате логов.
#### Исправления
- Исправлена ошибка с отсутствием прав доступа к `angie-syslog.sock`.
# https://angie.software/adc/docs.md
# О решении Angie ADC 1.0
Angie ADC — комплексное программное решение для
балансировки нагрузки и управления сетевым трафиком, включающее
балансировку на уровнях L4-L7, интеллектуальную доставку приложений и маршрутизацию,
а также глобальную DNS-балансировку (GSLB) и решения для обеспечения высокой доступности.
Angie ADC поддерживает мониторинг и управление через веб-интерфейс и командную строку (CLI),
а также предоставляет API для интеграции с внешними системами.
Решение Angie ADC поставляется в виде [аппаратного балансировщика](../hw)
и [виртуального устройства (Virtual Appliance)](https://angie.software//adc/docs/install/index.md#adc-installation).
См. также:
- [Установка и обновление](https://angie.software//adc/docs/install/index.md#adc-installation)
- [Начало работы](https://angie.software//adc/docs/getting-started/index.md#adc-getting-started)
## Функциональность Angie ADC
В таблице ниже приведены основные функции и возможности Angie ADC,
а также ссылки на соответствующие разделы документации.
| Функции | Документация |
|-------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Локальная балансировка нагрузки | [Балансировщик нагрузки](https://angie.software//adc/docs/load_balancer/index.md#adc-load-balancer) |
| Глобальная балансировка нагрузки (GSLB) | [Глобальная балансировка](https://angie.software//adc/docs/gslb/index.md#adc-gslb) |
| Решения для обеспечения высокой доступности и кластеризации | [IP-маршрутизация](https://angie.software//adc/docs/routing/index.md#adc-routing):
настройки высокой доступности для standalone-устройств Angie ADC
[Пара высокой доступности](https://angie.software//adc/docs/high-availability/index.md#adc-ha):
развертывание высокодоступного решения на базе двух Angie ADC
[Кластер](https://angie.software//adc/docs/clustering/create-cluster.md#adc-cluster): администрирование нескольких Angie ADC |
| Поддерживаемые протоколы и механизмы | [BGP](https://angie.software//adc/docs/routing/routing_bgp/index.md#adc-bgp), [OSPF](https://angie.software//adc/docs/routing/routing_ospf/index.md#adc-routing-ospf), [VRRP](https://angie.software//adc/docs/routing/vrrp/index.md#adc-vrrp),
[RHI](https://angie.software//adc/docs/routing/rhi.md#adc-rhi), RIP, [BFD](https://angie.software//adc/docs/routing/bfd.md#adc-bfd), WTF, RTFM |
| Инструменты для мониторинга и управления | [Мониторинг работы балансировщика нагрузки](https://angie.software//adc/docs/monitoring-and-statistics/index.md#adc-monitoring-and-statistics)
[Мониторинг системных метрик Angie ADC](https://angie.software//adc/docs/monitoring-and-statistics/system-metrics.md#adc-system-metrics)
[Аудит действий пользователей](https://angie.software//adc/docs/management/audit.md#adc-audit)
[Syslog](https://angie.software//adc/docs/management/logging.md#adc-syslog), [SNMP](https://angie.software//adc/docs/monitoring-and-statistics/snmp.md#adc-snmp)
[Управление через веб-интерфейс и CLI](https://angie.software//adc/docs/management/index.md#adc-management) |
## Текущая версия
Angie ADC **|adc_pdf_version|**
Также см. полную историю [версий Angie ADC](https://angie.software//adc/docs/adc-changes.md#adc-changes).
## Миграция с других решений
Angie ADC предлагает готовые примеры настройки функций
для быстрой замены решений от других производителей.
- [Миграция с OneConnect profile от F5](https://angie.software//adc/docs/adc-migration/keepalive-oneconnect.md#adc-keepalive-oneconnect)
- [Миграция с Use Source IP Mode (USIP) от Citrix NetScaler](https://angie.software//adc/docs/adc-migration/use-source-ip-mode.md#adc-usip)
Список будет пополняться.
# https://angie.software/adc/docs/install.md
# Установка и обновление
Решение Angie ADC поставляется
в виде виртуального устройства (Virtual Appliance)
и в виде [аппаратного балансировщика](../../hw).
При приобретении виртуального устройства Angie ADC вы можете выбрать
для установки один из следующих двух образов:
- [OVA](https://angie.software//adc/docs/install/install-ova.md#adc-install-ova) (Open Virtual Appliance VMWare) для VMware ESXi;
- [qcow2](https://angie.software//adc/docs/install/install-qcow2.md#adc-install-qcow2) (QEMU Copy-On-Write v2) для Linux-сред.
Образы собраны на базе операционной системы РЕД ОС 8.0.2.
## Аппаратные и программные требования
Минимальные аппаратные требования для запуска виртуального устройства Angie ADC:
- 2 vCPU
- 2 ГБ RAM
- 50 ГБ HDD
Поддерживаемые платформы виртуализации:
- KVM (QEMU)
- OpenStack
- VMware
В этом разделе:
- [Загрузка дистрибутива](https://angie.software//adc/docs/install/download.md#adc-download)
- [Запуск образа qcow2](https://angie.software//adc/docs/install/install-qcow2.md#adc-install-qcow2)
- [Запуск образа OVA](https://angie.software//adc/docs/install/install-ova.md#adc-install-ova)
- [Обновление Angie ADC](https://angie.software//adc/docs/install/update.md#adc-update)
- [Приложение: пути обновления Angie ADC](https://angie.software//adc/docs/install/upgrade-path.md#adc-upgrade-path)
- [Установка с помощью cloud-init](https://angie.software//adc/docs/install/cloud-init/index.md#adc-installation-ci)
# https://angie.software/adc/docs/install/download.md
# Загрузка дистрибутива
После покупки решения Angie ADC или получения пробной версии на вашу почту придет письмо с архивом,
содержащим файл `angie-adc-repo.p12` для скачивания дистрибутива через браузер,
а также c отдельными файлами сертификата и ключа, если вы планируете использовать curl.
Вы можете выбрать для установки один из двух образов Angie ADC из нашего репозитория:
- [OVA](https://angie.software//adc/docs/install/install-ova.md#adc-install-ova) (Open Virtual Appliance VMWare) для VMware vSphere, ESXi, VirtualBox;
- [qcow2](https://angie.software//adc/docs/install/install-qcow2.md#adc-install-qcow2) (QEMU Copy-On-Write v2) для Linux-сред.
Для загрузки дистрибутива через браузер вам необходимо:
- импортировать файл `angie-adc-repo.p12` в браузер с паролем, указанным в письме;
- открыть репозиторий по ссылке [https://download.angie.software/adc/](https://download.angie.software/adc/) и загрузить дистрибутив.
Пример команды для curl:
```console
$ curl -O https://download.angie.software/adc/angie-adc-1.0-x86_64.cloud-init.qcow2 \
--cert angie-adc-repo.crt \
--key angie-adc-repo.key
```
#### NOTE
Если выход в интернет осуществляется через прокси, то необходимо добавить домен репозитория в white-list,
либо загружать дистрибутив напрямую без использования прокси.
# https://angie.software/adc/docs/install/install-qcow2.md
# Запуск образа qcow2
Ниже приведены инструкции по локальному развертыванию виртуальной машины Angie ADC.
## Подготовка среды
Для работы необходима система виртуализации, например [qemu](https://www.qemu.org/docs/master/). Перед ее использованием убедитесь,
что у вас установлены следующие утилиты:
- **virsh**;
- **virt-install**;
- **qemu**;
- **libvirt**;
- **libguestfs-tools**;
- **virt-viewer**.
Установка **qemu** на Fedora:
```console
$ sudo dnf install qemu libvirt libguestfs-tools libguestfs virt-viewer virt-install
```
Установка **qemu** на Ubuntu и Debian:
```console
$ sudo apt update
$ sudo apt install -y \
qemu-kvm qemu-system-x86 qemu-utils \
libvirt-daemon-system libvirt-clients virtinst virt-manager \
ovmf cpu-checker
```
После установки необходимо добавить своего пользователя в соответствующие группы:
```console
$ sudo usermod -aG libvirt USER
$ sudo usermod -aG kvm USER
```
## Скачивание дистрибутива
Скачайте образ Angie ADC [из репозитория](https://angie.software//adc/docs/install/download.md#adc-download).
## Развертывание
Чтобы развернуть образ qcow2, выполните следующие действия:
1. Проверьте состояние виртуальной сети:
```console
$ sudo virsh net-list --all
```
2. Запустите дистрибутив Angie ADC.
Пример команды:
```console
$ sudo mv angie-adc-1.0-x86_64.cloud-init.qcow2 /var/lib/libvirt/images/
$ sudo virt-install --name angie-adc-1.0 --ram 2048 --disk /var/lib/libvirt/images/angie-adc-1.0-x86_64.cloud-init.qcow2 --os-variant generic --import
```
3. Перейдите в консоль виртуальной машины.
Откроется окно входа в мастер первоначальной настройки Angie ADC.
4. Введите логин `setup` и пароль `setup`.
Откроется мастер первоначальной настройки Angie ADC.
5. Выполните необходимые настройки сетевой конфигурации Angie ADC
и нажмите `exit`, чтобы выйти из мастера настройки.
Подробнее см. [Настройка в мастере](https://angie.software//adc/docs/getting-started/setup-wizard.md#adc-install-setup-wizard).
#### IMPORTANT
Минимально необходимо настроить хотя бы один сетевой интерфейс (вручную или с помощью DHCP).
6. Перейдите в веб-интерфейс Angie ADC по следующему адресу: `http://:8080`.
IP-адрес веб-интерфейса можно посмотреть в консоли ВМ или по команде
`sudo virsh net-dhcp-leases default`.
Откроется страница входа в веб-интерфейс Angie ADC.
7. Авторизуйтесь в Angie ADC.
Реквизиты для первого входа предоставляются после покупки решения.
Рекомендуется сменить пароль после первого входа.
В веб-интерфейсе Angie ADC вы можете настраивать функции Angie ADC
и просматривать статистику работы балансировщика нагрузки.
# https://angie.software/adc/docs/install/install-ova.md
# Запуск образа OVA
#### NOTE
Образ OVA собран для VMware ESXi 7.
При развертывании на более новых версиях ESXi (8, 9)
функции Angie ADC будут работать по совместимости.
## Подготовка среды
Для развертывания образа OVA необходима система виртуализации, например VMware ESXi.
## Скачивание дистрибутива
Скачайте образ Angie ADC [из репозитория](https://angie.software//adc/docs/install/download.md#adc-download).
## Развертывание
Чтобы развернуть образ OVA через веб-интерфейс VMware ESXi, выполните следующие действия:
1. Войдите в веб-интерфейс VMware ESXi через браузер.
2. В контекстном меню сервера выберите `Deploy OVF template`.
Откроется мастер развертывания.
3. Следуйте указаниям мастера, чтобы начать импорт образа Angie ADC.
В результате на сервере появится новая виртуальная машина.
4. Запустите виртуальную машину Angie ADC и перейдите в консоль ВМ.
Откроется окно входа в мастер первоначальной настройки Angie ADC.
5. Введите логин `setup` и пароль `setup`.
Откроется мастер первоначальной настройки Angie ADC.
6. Выполните необходимые настройки сетевой конфигурации Angie ADC
и нажмите `exit`, чтобы выйти из мастера настройки.
Подробнее см. [Настройка в мастере](https://angie.software//adc/docs/getting-started/setup-wizard.md#adc-install-setup-wizard).
#### IMPORTANT
Минимально необходимо настроить хотя бы один сетевой интерфейс (вручную или с помощью DHCP).
7. Перейдите в веб-интерфейс Angie ADC по следующему адресу: `http://:8080`.
IP-адрес веб-интерфейса можно посмотреть в консоли ВМ или по команде
`sudo virsh net-dhcp-leases default`.
Откроется страница входа в веб-интерфейс Angie ADC.
8. Авторизуйтесь в Angie ADC.
Реквизиты для первого входа предоставляются после покупки решения.
Рекомендуется сменить пароль после первого входа.
В веб-интерфейсе Angie ADC вы можете настраивать функции Angie ADC
и просматривать статистику работы балансировщика нагрузки.
# https://angie.software/adc/docs/install/update.md
# Обновление Angie ADC
Обновление Angie ADC выполняется
с помощью файла (файлов) обновления, которые находятся
по ссылке [https://download.angie.software/adc/updates/](https://download.angie.software/adc/updates/).
Поддерживается обновление Angie ADC следующих версий:
- с версии [1.0-rc1 до 1.0-rc2](#adc-update-1-0-rc1-to-1-0-rc2);
- с версии [0.8.2 до 1.0-rc1](#adc-update-0-8-2-to-1-0-rc1);
- с версии [0.8.x до 0.8.2](https://angie.software//adc/docs-0.8.2/install/update.md#adc082-update-0-8-x-to-0-8-2);
- с версии [0.8.0 до 0.8.1](https://angie.software//adc/docs-0.8.2/install/update.md#adc082-update-0-8-0-to-0-8-1);
- с версии [0.7.x до 0.8.1](https://angie.software//adc/docs-0.8.2/install/update.md#adc082-update-0-7-x-to-0-8-1);
- с версии [0.7.x до 0.7.3](https://angie.software//adc/docs-0.7.3/install/update.md#adc073-update-0-7-x-to-0-7-3);
- с версии [0.6.0 до версии 0.7.3](https://angie.software//adc/docs-0.7.3/install/update.md#adc073-update-0-6-0-to-0-7-3);
- с версии [0.5.x до версии 0.6.0](https://angie.software//adc/docs-0.6.0/install/update.md#adc060-update);
- с версии 0.5.0 до версии 0.5.2;
- с версии 0.4.0 до версии 0.5.0.
#### NOTE
Если для вашей исходной версии отсутствует прямое обновление до последней версии,
то рекомендуется последовательное обновление.
Пример пути обновления: 0.6.0 → 0.7.3 → 0.8.1 → 0.8.2 → 1.0-rc1 → 1.0-rc2.
Подробнее см. [приложение](https://angie.software//adc/docs/install/upgrade-path.md#adc-upgrade-path).
## Обновление с версии 1.0-rc1 до версии 1.0-rc2
Обновление Angie ADC с версии 1.0-rc1 до версии 1.0-rc2 выполняется
последовательно с помощью двух файлов обновления:
- `adc-update-1.0-rc1-to-1.0-rc2.stage1.angie`;
- `adc-update-1.0-rc1-to-1.0-rc2.stage2.angie`.
#### IMPORTANT
Сначала необходимо запустить первый файл обновления (до запуска второго файла),
иначе обновление завершится ошибкой.
#### IMPORTANT
После завершения обновления Angie ADC до версии 1.0-rc2 необходимо также обновить ядро системы.
Для этого перезагрузите Angie ADC в любой удобный момент (например в техническое окно
или в часы наименьшей нагрузки).
### Предварительные действия
- Скачайте файлы обновления `adc-update-1.0-rc1-to-1.0-rc2.stage1.angie`
и `adc-update-1.0-rc1-to-1.0-rc2.stage2.angie` из репозитория
по ссылке [https://download.angie.software/adc/updates/](https://download.angie.software/adc/updates/).
- Убедитесь, что файлы обновления имеют права 755, т.е. полный доступ (чтение, запись, выполнение)
есть только у владельца, а у группы и остальных — доступ на чтение и запуск.
- Расформируйте пару высокой доступности, если она была создана,
иначе обновление пары завершится ошибкой.
### Шаги обновления
1. Запустите [интерфейс командной строки](https://angie.software//adc/docs/management/cli-commands.md#adc-starting-cli) на порту 2222
и скопируйте файлы обновления
в корневую папку Angie ADC, сохраняя права файлов.
```none
$ scp -p -P 2222 adc-update-1.0-rc1-to-1.0-rc2.stage* admin@adc.example.com:/
```
#### NOTE
Если нет возможности скопировать файлы обновления с сохранением прав,
то права можно скорректировать на целевой системе клиентом **sftp**.
Пример для `adc-update-1.0-rc1-to-1.0-rc2.stage1.angie`:
```none
sftp -P 2222 admin@adc.example.com
admin@adc.example.com's password:
Connected to adc.example.com.
sftp> ls -l
---------- 1 0 0 379487220 May 21 10:07 adc-update-1.0-rc1-to-1.0-rc2.stage1.angie
sftp> chmod 755 adc-update-1.0-rc1-to-1.0-rc2.stage1.angie
Changing mode on /adc-update-1.0-rc1-to-1.0-rc2.stage1.angie
sftp> ls -l
-rwxr-xr-x 1 0 0 379487220 May 21 10:07 adc-update-1.0-rc1-to-1.0-rc2.stage1.angie
sftp>
```
2. Запустите первый файл обновления `adc-update-1.0-rc1-to-1.0-rc2.stage1.angie`:
```none
ssh -p 2222 admin@adc.example.com
admin@adc.example.com's password:
$$ system
(system)$$ upgrade adc-update-1.0-rc1-to-1.0-rc2.stage1.angie
WARNING!
==========
You are about to upgrade the ADC system.
This operation may cause service interruption.
IMPORTANT: Once started, the upgrade process CANNOT be interrupted!
Please make sure you have:
1. Scheduled maintenance window
2. Backed up your data
3. Notified relevant stakeholders
Do you want to proceed with the upgrade? [y/N] y
Checking script signature...
Verified OK
[2026-05-21 10:32:23] ADC Update Package
...
```
3. Запустите второй файл обновления `adc-update-1.0-rc1-to-1.0-rc2.stage2.angie`:
```none
ssh -p 2222 admin@adc.example.com
admin@adc.example.com's password:
$$ system
(system)$$ upgrade adc-update-1.0-rc1-to-1.0-rc2.stage2.angie
WARNING!
==========
You are about to upgrade the ADC system.
This operation may cause service interruption.
IMPORTANT: Once started, the upgrade process CANNOT be interrupted!
Please make sure you have:
1. Scheduled maintenance window
2. Backed up your data
3. Notified relevant stakeholders
Do you want to proceed with the upgrade? [y/N] y
Checking script signature...
Verified OK
[2026-05-21 10:42:23] ADC Update Package
...
```
В процессе обновления соединение с CLI Angie ADC может прерваться.
В таком случае через несколько минут заново подключитесь к CLI.
Чтобы просмотреть процесс обновления, перейдите в журнал событий обновления.
Если в сообщениях есть строка `Upgrade completed successfully`,
то обновление прошло успешно:
```none
$$ logs
(logs)$$ upgrade
...
[2026-05-21 11:43:17] Upgrade completed successfully
[2026-05-21 11:43:17] WARNING: All cli sessions may be terminated within the next 3 minutes to complete the upgrade procedure.
(logs)$$
```
## Обновление с версии 0.8.2 до версии 1.0-rc1
Обновление Angie ADC с версии 0.8.2 до версии 1.0-rc1 выполняется
последовательно с помощью двух файлов обновления:
- `adc-update-0.8.2-to-1.0-rc1.stage1.angie`;
- `adc-update-0.8.2-to-1.0-rc1.stage2.angie`.
#### IMPORTANT
Сначала необходимо запустить первый файл обновления (до запуска второго файла),
иначе обновление завершится ошибкой.
#### IMPORTANT
После завершения обновления Angie ADC до версии 1.0-rc1 необходимо также обновить ядро системы.
Для этого перезагрузите Angie ADC в любой удобный момент (например в техническое окно
или в часы наименьшей нагрузки).
### Предварительные действия
- Скачайте файлы обновления `adc-update-0.8.2-to-1.0-rc1.stage1.angie`
и `adc-update-0.8.2-to-1.0-rc1.stage2.angie` из репозитория
по ссылке [https://download.angie.software/adc/updates/](https://download.angie.software/adc/updates/).
- Убедитесь, что файлы обновления имеют права 755, т.е. полный доступ (чтение, запись, выполнение)
есть только у владельца, а у группы и остальных — доступ на чтение и запуск.
- Расформируйте пару высокой доступности, если она была создана,
иначе обновление пары завершится ошибкой.
### Шаги обновления
1. Запустите [интерфейс командной строки](https://angie.software//adc/docs/management/cli-commands.md#adc-starting-cli) на порту 2222
и скопируйте файлы обновления
в корневую папку Angie ADC, сохраняя права файлов.
```none
$ scp -p -P 2222 adc-update-0.8.2-to-1.0-rc1.stage* admin@adc.example.com:/
```
#### NOTE
Если нет возможности скопировать файлы обновления с сохранением прав,
то права можно скорректировать на целевой системе клиентом **sftp**.
Пример для `adc-update-0.8.2-to-1.0-rc1.stage1.angie`:
```none
sftp -P 2222 admin@adc.example.com
admin@adc.example.com's password:
Connected to adc.example.com.
sftp> ls -l
---------- 1 0 0 379487220 May 21 10:07 adc-update-0.8.2-to-1.0-rc1.stage1.angie
sftp> chmod 755 adc-update-0.8.2-to-1.0-rc1.stage1.angie
Changing mode on /adc-update-0.8.2-to-1.0-rc1.stage1.angie
sftp> ls -l
-rwxr-xr-x 1 0 0 379487220 May 21 10:07 adc-update-0.8.2-to-1.0-rc1.stage1.angie
sftp>
```
2. Запустите первый файл обновления `adc-update-0.8.2-to-1.0-rc1.stage1.angie`:
```none
ssh -p 2222 admin@adc.example.com
admin@adc.example.com's password:
$$ system
(system)$$ upgrade adc-update-0.8.2-to-1.0-rc1.stage1.angie
WARNING!
==========
You are about to upgrade the ADC system.
This operation may cause service interruption.
IMPORTANT: Once started, the upgrade process CANNOT be interrupted!
Please make sure you have:
1. Scheduled maintenance window
2. Backed up your data
3. Notified relevant stakeholders
Do you want to proceed with the upgrade? [y/N] y
Checking script signature...
Verified OK
[2026-05-21 10:32:23] ADC Update Package
...
```
3. Запустите второй файл обновления `adc-update-0.8.2-to-1.0-rc1.stage2.angie`:
```none
ssh -p 2222 admin@adc.example.com
admin@adc.example.com's password:
$$ system
(system)$$ upgrade adc-update-0.8.2-to-1.0-rc1.stage2.angie
WARNING!
==========
You are about to upgrade the ADC system.
This operation may cause service interruption.
IMPORTANT: Once started, the upgrade process CANNOT be interrupted!
Please make sure you have:
1. Scheduled maintenance window
2. Backed up your data
3. Notified relevant stakeholders
Do you want to proceed with the upgrade? [y/N] y
Checking script signature...
Verified OK
[2026-05-21 10:42:23] ADC Update Package
...
```
В процессе обновления соединение с CLI Angie ADC может прерваться.
В таком случае через несколько минут заново подключитесь к CLI.
Чтобы просмотреть процесс обновления, перейдите в журнал событий обновления.
Если в сообщениях есть строка `Upgrade completed successfully`,
то обновление прошло успешно:
```none
$$ logs
(logs)$$ upgrade
...
[2026-05-21 11:43:17] Upgrade completed successfully
[2026-05-21 11:43:17] WARNING: All cli sessions may be terminated within the next 3 minutes to complete the upgrade procedure.
(logs)$$
```
# https://angie.software/adc/docs/install/cloud-init.md
# Установка с помощью cloud-init
#### IMPORTANT
Установка с помощью cloud-init используется для Angie ADC до версии 0.5.2 включительно.
В этом разделе:
- [Развертывание образа qcow2 с cloud-init](https://angie.software//adc/docs/install/cloud-init/install-qcow2-0.5.2.md#adc-install-qcow2-0-5-2)
- [Развертывание образа OVA с cloud-init](https://angie.software//adc/docs/install/cloud-init/install-ova-0.5.2.md#adc-install-ova-0-5-2)
- [Настройка файла network-config для cloud-init](https://angie.software//adc/docs/install/cloud-init/install-cloud-init.md#adc-network-config)
# https://angie.software/adc/docs/install/cloud-init/install-qcow2-0.5.2.md
# Развертывание образа qcow2 с cloud-init
Развертывание Angie ADC состоит из следующих этапов:
- подготовка среды;
- подготовка ISO-образа **cloud-init** с минимальной конфигурацией сети;
- скачивание дистрибутива;
- развертывание образа qcow2.
Ниже приведены инструкции по локальному развертыванию виртуальной машины Angie ADC
с использованием ISO-образа **cloud-init** для тестирования решения.
При развертывании с помощью системы виртуализации также необходима поддержка **cloud-init** этой системой,
т.к. первоначальная настройка конфигурации Angie ADC возможна только с использованием **cloud-init**.
В будущих релизах планируется добавить возможность запуска Angie ADC без **cloud-init**.
## Подготовка среды
Для работы необходима система виртуализации, например [qemu](https://www.qemu.org/docs/master/). Перед ее использованием убедитесь,
что у вас установлены следующие утилиты:
- **virsh**;
- **virt-install**;
- **qemu**;
- **libvirt**;
- **libguestfs-tools**;
- **virt-viewer**.
Установка **qemu** на Fedora:
```console
$ sudo dnf install qemu libvirt libguestfs-tools libguestfs virt-viewer virt-install
```
Установка **qemu** на Ubuntu и Debian:
```console
$ sudo apt update
$ sudo apt install -y \
qemu-kvm qemu-system-x86 qemu-utils \
libvirt-daemon-system libvirt-clients virtinst virt-manager \
ovmf cpu-checker
```
После установки необходимо добавить своего пользователя в соответствующие группы:
```console
$ sudo usermod -aG libvirt USER
$ sudo usermod -aG kvm USER
```
## Подготовка ISO-образа
Для развертывания Angie ADC нужен ISO-образ **cloud-init**
с минимальной конфигурацией сети. **Cloud-init** является стандартным агентом инициализации
для виртуальных машин Linux.
При запуске виртуальной машины **cloud-init**
получает конфигурацию из ISO-образа в виде ранее заданных мета-данных и настраивает Angie ADC.
#### IMPORTANT
Рекомендуется всегда запускать виртуальную машину с ISO-образом **cloud-init**.
Отсутствие ISO-образа приведет к замедлению запуска и сбросу сетевых настроек Angie ADC.
Для подготовки конфигурации необходимы следующие файлы:
- `meta-data`
- `user-data`
- `network-config`
> #### NOTE
> Если необходимо задать дополнительные настройки, можно создать файл `vendor-data` и указать их в нем.
Шаги подготовки ISO-образа:
1. Создайте файл `meta-data` и укажите в нем базовую информацию о виртуальной машине Angie ADC.
Пример:
```yaml
instance-id: my-adc1 # уникальный идентификатор виртуальной машины
local-hostname: my-server # имя хоста виртуальной машины
```
2. Создайте файл `network-config` и задайте в нем конфигурацию сети.
Примеры для разных типов виртуализации смотрите [здесь](https://angie.software//adc/docs/install/cloud-init/install-cloud-init.md#adc-network-config).
Если вы используете DHCP, то файл `network-config` можно оставить пустым.
Для всех интерфейсов будет применен автоматический способ получения адреса.
3. Создайте файл `user-data`. В файле необходимо указать:
```console
#cloud-config
{}
```
В остальном содержимое файла будет игнорироваться, поэтому можно его не заполнять.
4. Проверьте конфигурацию для каждого файла:
```console
cloud-init schema --config-file user-data
```
```console
yamllint meta-data
```
```console
cloud-init schema --config-file network-config --schema-type network-config
```
Если конфигурация корректна, в выводе отобразится сообщение `Valid schema <файл>`.
5. Создайте ISO-образ, который **cloud-init** будет использовать при запуске.
Пример:
```console
genisoimage -output seed.iso -volid cidata -joliet -rock meta-data user-data network-config
```
## Скачивание дистрибутива
Скачайте образ Angie ADC [из репозитория](https://angie.software//adc/docs/install/download.md#adc-download).
## Развертывание
Чтобы развернуть образ qcow2, выполните следующие действия:
1. Проверьте состояние виртуальной сети:
```console
$ sudo virsh net-list --all
```
2. Запустите виртуальную машину c ISO-образом. Диск с конфигурацией `seed.iso`
необходимо подключить как CD-ROM при запуске.
Пример команды для запуска виртуальной машины на KVM (QEMU) с использованием `virt-install`:
```console
virt-install \
--virt-type kvm \
--name adc \
--ram 2048 \
--vcpus 2 \
--disk angie-adc-0.5.2-x86_64.cloud-init.qcow2,format=qcow2 \
--disk seed.iso,device=cdrom \
--network=bridge:virbr0 \
--graphics vnc,listen=0.0.0.0 \
--os-variant=centos8 \
--import
```
После выполнения команды откроется консоль виртуального устройства в
приложении **virt-viewer**.
3. Посмотрите IP-адрес веб-интерфейса Angie ADC:
```console
$ sudo virsh net-dhcp-leases default
```
4. Откройте в браузере адрес `http://<адрес_веб-интерфейса>:8080`.
Откроется страница входа в веб-интерфейс Angie ADC. Реквизиты для первого входа предоставляются
после покупки решения. Рекомендуется сменить пароль после первого входа.
В [веб-интерфейсе Angie ADC](https://angie.software//adc/docs/management/adc-console.md#adc-console) вы можете настраивать функции Angie ADC
и просматривать статистику работы балансировщика нагрузки.
Также доступно управление через [интерфейс командной строки (CLI)](https://angie.software//adc/docs/management/cli-commands.md#adc-cli-commands).
#### NOTE
Сервис SSH по умолчанию не запущен.
При запуске внутреннее имя виртуального устройства
будет задано как `angie-va`.
Вы можете изменить имя хоста и настройки (сеть, часовой пояс)
через ISO-образ **cloud-init**
или в программах, поддерживающих **cloud-init** вашей системы виртуализации.
# https://angie.software/adc/docs/install/cloud-init/install-ova-0.5.2.md
# Развертывание образа OVA с cloud-init
Развертывание Angie ADC состоит из следующих этапов:
- подготовка среды;
- подготовка ISO-образа **cloud-init** с минимальной конфигурацией сети;
- скачивание дистрибутива;
- развертывание образа OVA.
При развертывании с помощью системы виртуализации необходима поддержка **cloud-init** этой системой,
т.к. первоначальная настройка конфигурации Angie ADC возможна только с использованием **cloud-init**.
В будущих релизах планируется добавить возможность запуска Angie ADC без **cloud-init**.
#### NOTE
Образ OVA собран для VMware ESXi 7.
При развертывании на более новых версиях ESXi (8, 9)
функции Angie ADC будут работать по совместимости.
## Подготовка среды
Для развертывания образа OVA необходима система виртуализации, например VMware ESXi.
Настройка ISO-образа **cloud-init** выполняется в Linux-среде (Fedora, Ubuntu, Debian).
## Подготовка ISO-образа
Для развертывания Angie ADC нужен ISO-образ **cloud-init**
с минимальной конфигурацией сети. **Cloud-init** является стандартным агентом инициализации
для виртуальных машин Linux.
При запуске виртуальной машины **cloud-init**
получает конфигурацию из ISO-образа в виде ранее заданных мета-данных и настраивает Angie ADC.
#### IMPORTANT
Рекомендуется всегда запускать виртуальную машину с ISO-образом **cloud-init**.
Отсутствие ISO-образа приведет к замедлению запуска и сбросу сетевых настроек Angie ADC.
Для подготовки конфигурации необходимы следующие файлы:
- `meta-data`
- `user-data`
- `network-config`
> #### NOTE
> Если необходимо задать дополнительные настройки, можно создать файл `vendor-data` и указать их в нем.
Шаги подготовки ISO-образа:
1. Создайте файл `meta-data` и укажите в нем базовую информацию о виртуальной машине Angie ADC.
Пример:
```yaml
instance-id: my-adc1 # уникальный идентификатор виртуальной машины
local-hostname: my-server # имя хоста виртуальной машины
```
2. Создайте файл `network-config` и задайте в нем конфигурацию сети.
Примеры для разных типов виртуализации смотрите [здесь](https://angie.software//adc/docs/install/cloud-init/install-cloud-init.md#adc-network-config).
Если вы используете DHCP, то файл `network-config` можно оставить пустым.
Для всех интерфейсов будет применен автоматический способ получения адреса.
3. Создайте файл `user-data`. В файле необходимо указать:
```console
#cloud-config
{}
```
В остальном содержимое файла будет игнорироваться, поэтому можно его не заполнять.
4. Проверьте конфигурацию для каждого файла:
```console
cloud-init schema --config-file user-data
```
```console
yamllint meta-data
```
```console
cloud-init schema --config-file network-config --schema-type network-config
```
Если конфигурация корректна, в выводе отобразится сообщение `Valid schema <файл>`.
5. Создайте ISO-образ, который **cloud-init** будет использовать при запуске.
Пример:
```console
genisoimage -output seed.iso -volid cidata -joliet -rock meta-data user-data network-config
```
## Скачивание дистрибутива
Скачайте образ Angie ADC [из репозитория](https://angie.software//adc/docs/install/download.md#adc-download).
## Развертывание
Чтобы развернуть образ OVA через веб-интерфейс VMware ESXi, выполните следующие действия:
1. Войдите в веб-интерфейс VMware ESXi через браузер.
2. В контекстном меню сервера выберите `Deploy OVF template`.
Откроется мастер развертывания.
3. Следуйте указаниям мастера, чтобы начать импорт образа Angie ADC.
В результате на сервере появится новая виртуальная машина.
4. Включите CD/DVD-ROM и подключите к нему ISO-образ для первоначальной настройки сети в Angie ADC.
Для этого:
4.1. Перейдите в настройки оборудования виртуальной машины и выберите `Edit Settings`.
4.2. Выберите `Add New Device` → `CD/DVD Drive`.
4.3. Выберите источник `Client Device` и укажите путь к файлу ISO (например `seed.iso`).
4.4. Установите флажок `Connect at power on`, чтобы включить автоподключение.
4.5. Сохраните настройки, нажав `OK`.
5. Запустите созданную виртуальную машину.
6. В консоли созданной виртуальной машины посмотрите IP-адрес веб-интерфейса Angie ADC.
7. Перейдите в веб-интерфейс. Для этого откройте в браузере `http://<адрес_веб-интерфейса>:8080`.
Откроется страница входа в веб-интерфейс Angie ADC. Реквизиты для первого входа предоставляются
после покупки решения. Рекомендуется сменить пароль после первого входа.
В [веб-интерфейсе Angie ADC](https://angie.software//adc/docs/management/adc-console.md#adc-console) вы можете настраивать функции Angie ADC
и просматривать статистику работы балансировщика нагрузки.
Также доступно управление через [интерфейс командной строки (CLI)](https://angie.software//adc/docs/management/cli-commands.md#adc-cli-commands).
#### NOTE
Сервис SSH по умолчанию не запущен.
При запуске внутреннее имя виртуального устройства
будет задано как `angie-va`.
Вы можете изменить имя хоста и настройки (сеть, часовой пояс)
через ISO-образ **cloud-init**
или в программах, поддерживающих **cloud-init** вашей системы виртуализации.
# https://angie.software/adc/docs/install/cloud-init/install-cloud-init.md
# Настройка файла network-config для cloud-init
В файле `network-config` задается конфигурация сети.
Ниже приведены примеры для разных типов виртуализации.
#### NOTE
Если вы используете DHCP, то файл `network-config` можно оставить пустым.
Для всех интерфейсов будет применен автоматический способ получения адреса.
## Образ OVA
### Сетевой драйвер E1000
Статические адреса настраиваются на интерфейсах от 1 до 3.
Имена интерфейсов: `ens33`, `ens37`, `ens38`.
Пример:
```yaml
#cloud-config
network:
version: 2
ethernets:
ens33:
dhcp4: false
addresses:
- 192.168.100.155/24
gateway4: 192.168.100.1
nameservers:
addresses: [8.8.8.8, 1.1.1.1]
search: [example.com]
ens37:
dhcp4: false
addresses:
- 192.168.110.155/24
gateway4: 192.168.110.1
nameservers:
addresses: [8.8.8.8, 1.1.1.1]
search: [example.com]
ens38:
dhcp4: false
addresses:
- 192.168.120.155/24
gateway4: 192.168.120.1
nameservers:
addresses: [8.8.8.8, 1.1.1.1]
search: [example.com]
```
### Сетевой драйвер VMXNET
Статические адреса настраиваются на интерфейсах от 1 до 3.
Имена интерфейсов: `ens160`, `ens192`, `ens224`.
Пример:
```yaml
#cloud-config
network:
version: 2
ethernets:
ens160:
dhcp4: false
addresses:
- 192.168.100.155/24
gateway4: 192.168.100.1
nameservers:
addresses: [8.8.8.8, 1.1.1.1]
search: [example.com]
ens192:
dhcp4: false
addresses:
- 192.168.110.155/24
gateway4: 192.168.110.1
nameservers:
addresses: [8.8.8.8, 1.1.1.1]
search: [example.com]
ens224:
dhcp4: false
addresses:
- 192.168.120.155/24
gateway4: 192.168.120.1
nameservers:
addresses: [8.8.8.8, 1.1.1.1]
search: [example.com]
```
## Образ qcow2
Статические адреса настраиваются на интерфейсах от 1 до 3.
Имена интерфейсов: `enp1s0`, `enp2s0`, `enp3s0`.
Пример:
```yaml
#cloud-config
network:
version: 2
ethernets:
enp1s0:
dhcp4: false
addresses:
- 192.168.100.155/24
gateway4: 192.168.100.1
nameservers:
addresses: [8.8.8.8, 1.1.1.1]
search: [example.com]
enp2s0:
dhcp4: false
addresses:
- 192.168.110.155/24
gateway4: 192.168.110.1
nameservers:
addresses: [8.8.8.8, 1.1.1.1]
search: [example.com]
enp3s0:
dhcp4: false
addresses:
- 192.168.120.155/24
gateway4: 192.168.120.1
nameservers:
addresses: [8.8.8.8, 1.1.1.1]
search: [example.com]
```
# https://angie.software/adc/docs/install/upgrade-path.md
# Приложение: пути обновления Angie ADC
Начиная с версии 0.4.0, поддерживается обновление Angie ADC с помощью файла(ов) обновления.
Все файлы обновления можно просмотреть и скачать по ссылке [https://download.angie.software/adc/updates/](https://download.angie.software/adc/updates/).
Инструкции по обновлению см. [Обновление Angie ADC](https://angie.software//adc/docs/install/update.md#adc-update).
В таблице ниже приведены пути обновления до текущей версии Angie ADC.
В левом столбце указаны исходные версии, а в верхней строке — целевые версии,
до которых можно обновиться.
В ячейках приведены ссылки на скачивание файлов обновления соответствующих версий.
#### NOTE
Если для вашей исходной версии отсутствует прямое обновление до последней версии,
то рекомендуется последовательное обновление.
Пример пути обновления: 0.6.0 → 0.7.3 → 0.8.1 → 0.8.2 → 1.0-rc1 → 1.0-rc2.
| Версия | 0.5.0 | 0.5.2 | 0.6.0 | 0.7.0 | 0.7.1 | 0.7.2 | 0.7.3 | 0.8.0 | 0.8.1 | 0.8.2 | 1.0-rc1 | 1.0-rc2 |
|----------|-----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 0.4.0 | [0.4.0-to-0.5.0](https://download.angie.software/adc/updates/adc-update-0.4.0-to-0.5.0.angie) | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- |
| 0.5.0 | -- | [0.5.0-to-0.5.2](https://download.angie.software/adc/updates/adc-update-0.5.0-to-0.5.2.angie) | [0.5.x-to-0.6.0](https://download.angie.software/adc/updates/adc-update-0.5.x-to-0.6.0.angie) | -- | -- | -- | -- | -- | -- | -- | -- | -- |
| 0.5.2 | -- | -- | [0.5.x-to-0.6.0](https://download.angie.software/adc/updates/adc-update-0.5.x-to-0.6.0.angie) | -- | -- | -- | -- | -- | -- | -- | -- | -- |
| 0.6.0 | -- | -- | -- | -- | [0.6.0-to-0.7.1.stage1](https://download.angie.software/adc/updates/adc-update-0.6.0-to-0.7.1.stage1.angie)
[0.6.0-to-0.7.1.stage2](https://download.angie.software/adc/updates/adc-update-0.6.0-to-0.7.1.stage2.angie)
[0.6.0-to-0.7.x.stage3](https://download.angie.software/adc/updates/adc-update-0.6.0-to-0.7.x.stage3.angie) | [0.6.0-to-0.7.2.stage1](https://download.angie.software/adc/updates/adc-update-0.6.0-to-0.7.2.stage1.angie)
[0.6.0-to-0.7.2.stage2](https://download.angie.software/adc/updates/adc-update-0.6.0-to-0.7.2.stage2.angie)
[0.6.0-to-0.7.x.stage3](https://download.angie.software/adc/updates/adc-update-0.6.0-to-0.7.x.stage3.angie) | [0.6.0-to-0.7.3.stage1](https://download.angie.software/adc/updates/adc-update-0.6.0-to-0.7.3.stage1.angie)
[0.6.0-to-0.7.3.stage2](https://download.angie.software/adc/updates/adc-update-0.6.0-to-0.7.3.stage2.angie)
[0.6.0-to-0.7.x.stage3](https://download.angie.software/adc/updates/adc-update-0.6.0-to-0.7.x.stage3.angie) | -- | -- | -- | -- | -- |
| 0.7.0 | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- |
| 0.7.1 | -- | -- | -- | -- | -- | [0.7.x-to-0.7.2](https://download.angie.software/adc/updates/adc-update-0.7.x-to-0.7.2.angie) | [0.7.x-to-0.7.3](https://download.angie.software/adc/updates/adc-update-0.7.x-to-0.7.3.angie) | [0.7.x-to-0.8.0.stage1](https://download.angie.software/adc/updates/adc-update-0.7.x-to-0.8.0.stage1.angie)
[0.7.x-to-0.8.0.stage2](https://download.angie.software/adc/updates/adc-update-0.7.x-to-0.8.0.stage2.angie) | [0.7.x-to-0.8.1.stage1](https://download.angie.software/adc/updates/adc-update-0.7.x-to-0.8.1.stage1.angie)
[0.7.x-to-0.8.1.stage2](https://download.angie.software/adc/updates/adc-update-0.7.x-to-0.8.1.stage2.angie) | -- | -- | -- |
| 0.7.2 | -- | -- | -- | -- | -- | -- | [0.7.x-to-0.7.3](https://download.angie.software/adc/updates/adc-update-0.7.x-to-0.7.3.angie) | [0.7.x-to-0.8.0.stage1](https://download.angie.software/adc/updates/adc-update-0.7.x-to-0.8.0.stage1.angie)
[0.7.x-to-0.8.0.stage2](https://download.angie.software/adc/updates/adc-update-0.7.x-to-0.8.0.stage2.angie) | [0.7.x-to-0.8.1.stage1](https://download.angie.software/adc/updates/adc-update-0.7.x-to-0.8.1.stage1.angie)
[0.7.x-to-0.8.1.stage2](https://download.angie.software/adc/updates/adc-update-0.7.x-to-0.8.1.stage2.angie) | -- | -- | -- |
| 0.7.3 | -- | -- | -- | -- | -- | -- | -- | [0.7.x-to-0.8.0.stage1](https://download.angie.software/adc/updates/adc-update-0.7.x-to-0.8.0.stage1.angie)
[0.7.x-to-0.8.0.stage2](https://download.angie.software/adc/updates/adc-update-0.7.x-to-0.8.0.stage2.angie) | [0.7.x-to-0.8.1.stage1](https://download.angie.software/adc/updates/adc-update-0.7.x-to-0.8.1.stage1.angie)
[0.7.x-to-0.8.1.stage2](https://download.angie.software/adc/updates/adc-update-0.7.x-to-0.8.1.stage2.angie) | -- | -- | -- |
| 0.8.0 | -- | -- | -- | -- | -- | -- | -- | -- | [0.8.0-to-0.8.1.stage1](https://download.angie.software/adc/updates/adc-update-0.8.0-to-0.8.1.stage1.angie)
[0.8.0-to-0.8.1.stage2](https://download.angie.software/adc/updates/adc-update-0.8.0-to-0.8.1.stage2.angie) | [0.8.x-to-0.8.2.stage1](https://download.angie.software/adc/updates/adc-update-0.8.x-to-0.8.2.stage1.angie)
[0.8.x-to-0.8.2.stage2](https://download.angie.software/adc/updates/adc-update-0.8.x-to-0.8.2.stage2.angie) | -- | -- |
| 0.8.1 | -- | -- | -- | -- | -- | -- | -- | -- | -- | [0.8.x-to-0.8.2.stage1](https://download.angie.software/adc/updates/adc-update-0.8.x-to-0.8.2.stage1.angie)
[0.8.x-to-0.8.2.stage2](https://download.angie.software/adc/updates/adc-update-0.8.x-to-0.8.2.stage2.angie) | -- | -- |
| 0.8.2 | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | [0.8.2-to-1.0-rc1.stage1](https://download.angie.software/adc/updates/adc-update-0.8.2-to-1.0-rc1.stage1.angie)
[0.8.2-to-1.0-rc1.stage2](https://download.angie.software/adc/updates/adc-update-0.8.2-to-1.0-rc1.stage2.angie) | -- |
| 1.0-rc1 | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | [1.0-rc1-to-1.0-rc2.stage1](https://download.angie.software/adc/updates/adc-update-1.0-rc1-to-1.0-rc2.stage1.angie)
[1.0-rc1-to-1.0-rc2.stage2](https://download.angie.software/adc/updates/adc-update-1.0-rc1-to-1.0-rc2.stage2.angie) |
# https://angie.software/adc/docs/getting-started.md
# Начало работы
После установки и запуска виртуального образа Angie ADC
рекомендуется выполнить общую настройку системы:
- настроить сеть;
- получить доступ к веб-интерфейсу;
- добавить пользователей и настроить авторизацию;
- настроить синхронизацию времени и конфигурацию балансировщика нагрузки.
Дополнительно можно настроить высокую доступность, кластеризацию и глобальную балансировку.
В этом разделе:
- [Общая настройка системы](https://angie.software//adc/docs/getting-started/deploy.md#adc-deploy-scenario)
- [Настройка в мастере](https://angie.software//adc/docs/getting-started/setup-wizard.md#adc-install-setup-wizard)
- [Настройка сетевых интерфейсов через веб-интерфейс](https://angie.software//adc/docs/getting-started/network-config.md#adc-network-config)
- [Подключение внешних пользователей](https://angie.software//adc/docs/getting-started/users/index.md#adc-external-users)
# https://angie.software/adc/docs/getting-started/deploy.md
# Общая настройка системы
После [установки и запуска](https://angie.software//adc/docs/install/index.md#adc-installation) виртуального образа Angie ADC
рекомендуется выполнить общую настройку системы и затем настроить
конфигурацию балансировщика нагрузки.
## Базовая настройка системы
1. Задайте сетевую конфигурацию Angie ADC через
[мастер настройки](https://angie.software//adc/docs/getting-started/setup-wizard.md#adc-install-setup-wizard).
#### NOTE
Минимально необходимо настроить хотя бы один сетевой интерфейс (вручную или с помощью DHCP).
После этого у вас появится доступ к веб-интерфейсу Angie ADC
по адресу `http://:8080`.
IP-адрес веб-интерфейса можно посмотреть в консоли ВМ или по команде
`sudo virsh net-dhcp-leases default`.
Реквизиты для первого входа предоставляются после покупки решения.
Рекомендуется сменить пароль для локального пользователя `admin`
после первого входа в веб-интерфейс.
2. Донастройте сетевые интерфейсы
[через веб-интерфейс](https://angie.software//adc/docs/getting-started/network-config.md#adc-network-config), если это необходимо.
3. Добавьте пользователей системы и настройте для них аутентификацию и авторизацию
(поддерживаются [локальные](https://angie.software//adc/docs/management/system/managing-users.md#adc-managing-users)
и [внешние пользователи](https://angie.software//adc/docs/getting-started/users/index.md#adc-external-users)).
4. Настройте [синхронизацию времени по NTP](https://angie.software//adc/docs/management/system/ntp.md#adc-ntp).
5. Настройте [конфигурацию балансировщика нагрузки](https://angie.software//adc/docs/load_balancer/index.md#adc-load-balancer).
## Расширенная настройка
После выполнения общей настройки системы дополнительно можно настроить:
- высокую доступность для [standalone-устройства Angie ADC](https://angie.software//adc/docs/routing/index.md#adc-routing);
- [кластеризацию Angie ADC](https://angie.software//adc/docs/clustering/create-cluster.md#adc-cluster);
- пару высокой доступности [для двух устройств Angie ADC](https://angie.software//adc/docs/high-availability/creating-ha-pair.md#adc-ha-create) (требует кластер);
- использование [сертификатов](https://angie.software//adc/docs/management/certificates.md#adc-certificates)
(требует кластер);
- [глобальную балансировку](https://angie.software//adc/docs/gslb/index.md#adc-gslb) (требует кластер).
## Мониторинг
В веб-интерфейсе Angie ADC вам доступны:
- [Мониторинг работы балансировщика нагрузки](https://angie.software//adc/docs/monitoring-and-statistics/viewing-statistics.md#adc-viewing-statistics);
- [Мониторинг системных метрик Angie ADC](https://angie.software//adc/docs/monitoring-and-statistics/system-metrics.md#adc-system-metrics).
## Логирование
Поддерживаются:
- просмотр [журналов событий](https://angie.software//adc/docs/management/cli-commands.md#adc-cli-logs);
- подключение [syslog-сервера](https://angie.software//adc/docs/management/logging.md#adc-syslog) для экспорта логов;
- отправка метрик [по протоколу SNMPv2c](https://angie.software//adc/docs/monitoring-and-statistics/snmp.md#adc-snmp).
## Примеры типовых схем развертывания Angie ADC
- В рамках одного дата-центра (DC) для локальной балансировки трафика:
Рис. 1
- В двух и более дата-центрах с поддержкой резервирования и глобального управления трафиком (GSLB):
Рис. 2
См. также:
- [Установка и обновление](https://angie.software//adc/docs/install/index.md#adc-installation);
- [Балансировщик нагрузки](https://angie.software//adc/docs/load_balancer/index.md#adc-load-balancer).
# https://angie.software/adc/docs/getting-started/setup-wizard.md
# Настройка в мастере
Мастер настройки позволяет управлять конфигурацией Angie ADC.
Также в мастере можно просмотреть сетевую конфигурацию и проверить доступность узла, выполнив ping-запрос.
**При первом запуске** Angie ADC вам необходимо настроить хотя бы один [сетевой интерфейс](#adc-frw-interfaces)
для доступа к веб-интерфейсу Angie ADC.
**При расширенной настройке** вы можете дополнительно настроить другие интерфейсы, бонды и VLAN-интерфейсы,
назначить выделенный интерфейс управления, изменить имя устройства и порт для веб-интерфейса.
**Для входа в мастер** необходимо перейти в консоль виртуальной машины
и в окне входа в мастер ввести предустановленные
логин `setup` и пароль `setup`.
Чтобы выйти из мастера настройки Angie ADC, нажмите `exit` в основном меню.
В этой статье:
- [Меню мастера](#adc-frw-menu);
- [Настройка сетевых интерфейсов](#adc-frw-interfaces);
- [Настройка интерфейса управления](#adc-frw-mgmt);
- [Смена портов для веб-интерфейса Angie ADC](#adc-frw-port);
- [Создание бондов](#adc-frw-bonds);
- [Создание VLAN-интерфейсов](#adc-frw-vlans);
- [Просмотр конфигурации Angie ADC и сетевых настроек](#adc-frw-system);
- [Изменение имени устройства Angie ADC](#adc-frw-hostname);
- [Проверка доступности узла](#adc-frw-ping).
## Меню мастера
Основное меню мастера настройки Angie ADC содержит следующие команды:
- `info` — просмотр общей информации об Angie ADC.
- `mgmt` — настройка интерфейса управления Angie ADC.
- `interfaces` — переход к просмотру и настройке сетевых интерфейсов, бондов и VLAN-интерфейсов.
- `bond` — переход к созданию, просмотру и удалению сетевых бондов.
- `vlan` — переход к созданию, просмотру и удалению VLAN-интерфейсов.
- `web interface` — изменение порта для веб-интерфейса Angie ADC.
- `hostname` — смена имени устройства.
- `config` — просмотр конфигурации Angie ADC и сетевых настроек.
- `ping` — проверка доступности узла.
- `exit` — выход из мастера.
## Настройка сетевых интерфейсов
Чтобы настроить сетевой интерфейс Angie ADC, выполните следующие действия:
1. Выберите в основном меню пункт `interfaces`.
Откроется список доступных интерфейсов.
2. Выберите интерфейс и перейдите в его меню.
Откроется список доступных действий:
- `show` — просмотр информации об интерфейсе.
- `config` — переход к ручной настройке IP-адреса и шлюза (Gateway).
- `dhcp` — настройка автоматического получения IP-адреса от DHCP-сервера.
- `mtu` — переход к настройке MTU.
- `clear` — сброс всех заданных настроек интерфейса, кроме MTU. Значение MTU,
заданное вручную, не сбрасываются.
- `back` — выход из меню интерфейса.
3. Выберите `config` или `dhcp` в зависимости от ваших целей
и задайте необходимые настройки.
## Настройка интерфейса управления
Рекомендуется использовать для управления отдельную сеть, в которой нет служебных сервисов,
иначе эти сервисы перестанут быть доступными для других компонентов Angie ADC.
Если вы хотите сохранить доступ к этим сервисам, после выделения интерфейса управления
настройте для них маршруты-исключения.
Чтобы выделить отдельный интерфейс для управления Angie ADC,
выполните следующие действия:
1. Выберите в основном меню пункт `mgmt`.
Откроется список доступных действий:
- `setup` — переход к настройке интерфейса управления.
- `status` — просмотр текущего статуса интерфейса управления.
- `leak` — переход к настройке маршрутов-исключений для сервисов внутри сети управления
(пункт отображается, если интерфейс управления настроен).
- `back` — выход из меню `mgmt`.
2. В открывшемся меню выберите `setup`.
Откроется список доступных интерфейсов.
3. Выберите нужный интерфейс.
Этот интерфейс будет использоваться для управления системой через отдельную сеть
и будет иметь собственную таблицу маршрутизации.
4. Подтвердите операцию.
#### IMPORTANT
Служебные сервисы, расположенные в этой сети, перестанут быть доступными
для других компонентов Angie ADC.
5. Если необходимо, настройте маршруты-исключения для служебных сервисов.
Для этого перейдите в меню `mgmt` → `leak`
→ `add` и добавьте сеть назначения, из которой будет производиться доступ
к сервисам, находящимся в сети управления.
## Создание бондов
При создании бондов используется протокол LACP (802.3ad)
и режим active (интерфейс инициирует создание агрегированного канала).
Чтобы объединить несколько физических интерфейсов в один логический интерфейс (бонд),
выполните следующие действия:
1. Выберите в основном меню пункт `bond`.
Откроется список доступных действий:
- `list` — просмотр списка бондов.
- `create` — переход к созданию нового бонда.
- `back` — выход из меню `bond`.
2. Выберите `create`, укажите номер бонда (по умолчанию будет предложен первый свободный номер по возрастанию)
и нажмите `OK`.
3. Выберите интерфейсы, которые необходимо объединить (максимум 8 интерфейсов), и нажмите `OK`.
#### IMPORTANT
Рекомендуется объединять в бонд ненастроенные сетевые интерфейсы.
4. В открывшемся окне с конфигурацией подтвердите создание нового бонда.
Просмотр свойств бонда и его удаление доступны через основное меню
`bond` → `list` → ``.
Настройка бонда доступна через основное меню настройки интерфейсов:
`interfaces` → ``.
## Создание VLAN-интерфейсов
Чтобы настроить VLAN-интерфейс, выполните следующие действия:
1. Выберите в основном меню пункт `vlan`.
Откроется список доступных действий:
- `list` — просмотр списка VLAN-интерфейсов.
- `create` — переход к созданию нового VLAN-интерфейса.
- `back` — выход из меню `vlan`.
2. Выберите `create`, укажите родительский интерфейс,
VLAN ID для нового VLAN и нажмите `OK`.
Будет создан новый VLAN-интерфейс.
Просмотр свойств VLAN и его удаление доступны через основное меню
`vlan` → `list` → ``.
Настройка VLAN доступна через основное меню настройки интерфейсов:
`interfaces` → ``.
## Просмотр конфигурации Angie ADC и сетевых настроек
Чтобы просмотреть текущую конфигурацию Angie ADC или
конфигурацию systemd-networkd для заданных сетей,
выполните следующие действия:
1. Выберите в основном меню пункт `config`.
Откроется список доступных действий:
- `system` — просмотр сетевой конфигурации Angie ADC.
- `network` — просмотр конфигурации systemd-networkd для заданных сетей.
- `back` — выход из меню `config`.
2. Выберите `system`, чтобы просмотреть текущую конфигурацию Angie ADC.
3. Выберите `network` → `<имя сети>`, чтобы
просмотреть настройки systemd-networkd для этой сети.
## Смена портов для веб-интерфейса Angie ADC
Вы можете назначить для веб-интерфейса Angie ADC любой незанятый порт.
Чтобы изменить порты по умолчанию, выполните следующие действия:
1. Выберите в основном меню пункт `web interface`.
Откроется список доступных действий:
- `set` — назначение новых портов.
- `reset` — восстановление настроек по умолчанию.
- `logs` — просмотр журнала.
- `back` — выход из меню `web interface`.
2. Выберите `set`, укажите новые значения портов и примените настройки.
## Изменение имени устройства Angie ADC
Чтобы изменить имя устройства Angie ADC, выполните следующие действия:
1. Выберите в основном меню пункт `hostname`.
2. В открывшемся окне введите новое имя устройства и сохраните изменения.
## Проверка доступности узла
Чтобы проверить доступность узла с помощью ping-запроса, выполните следующие действия:
1. Выберите в основном меню пункт `ping`.
2. В открывшемся окне введите имя или IP-адрес узла,
доступность которого нужно проверить.
# https://angie.software/adc/docs/getting-started/network-config.md
# Настройка сетевых интерфейсов через веб-интерфейс
Вы можете просматривать и изменять параметры сетевых интерфейсов
в веб-интерфейсе Angie ADC (`Система` → `Конфигурация`).
#### IMPORTANT
Не рекомендуется изменять настройки интрфейсов узлов, объединенных
в пару высокой доступности, иначе пара может потерять связность и работоспособность.
## Изменение параметров сетевого интерфейса
1. В веб-интерфейсе Angie ADC перейдите `Система` → `Конфигурация`.
2. В блоке `Сетевые интерфейсы` нажмите на сетевой интерфейс,
параметры которого вы хотите изменить.
Откроется окно с параметрами выбранного сетевого интерфейса.
#### NOTE
Если для интерфейса был указан способ получения настроек по DHCP,
то в окне редактирования будет отображаться подсказка
с DHCP-параметрами интерфейса.
3. Внесите необходимые изменения и нажмите `Сохранить`.
Также изменение параметров сетевых интерфейсов доступно через [CLI](https://angie.software//adc/docs/management/cli-commands.md#adc-cli-config-set)
и [в мастере](https://angie.software//adc/docs/getting-started/setup-wizard.md#adc-install-setup-wizard).
## Просмотр параметров сетевого интерфейса
В блоке `Сетевые интерфейсы` отображается список настроенных сетевых интерфейсов.
Для каждого интерфейса отображаются следующие параметры:
- Имя сетевого интерфейса.
- MAC-адрес (формат: `"XX:XX:XX:XX:XX:XX"`).
- Тип конфигурации: `static`, `DHCP`.
- Массив IPv4-адресов в формате CIDR.
- Массив IPv6-адресов в формате CIDR.
- IP-адрес шлюза по умолчанию (глобальный для всех интерфейсов), если установлен.
- Массив IP-адресов DNS-серверов.
- Массив доменов поиска DNS.
# https://angie.software/adc/docs/getting-started/users.md
# Подключение внешних пользователей
При использовании внешнего провайдера аутентификации и авторизации
данные о пользователях хранятся на внешнем сервере.
Вы можете настроить аутентификацию и авторизацию внешних пользователей
в Angie ADC через провайдеров RADIUS, TACACS и LDAP.
Пользователям можно назначить одну из следующих ролей:
- `Администратор`: обладает полными правами на все действия в системе;
- `Супервизор`: может только просматривать информацию в системе.
Для включения внешней аутентификации и авторизации необходимо
добавить в систему предварительно настроенный сервер.
После этого при входе в веб-интерфейс будет доступен выбор
типа аутентификации.
В этом разделе:
- [RADIUS](https://angie.software//adc/docs/getting-started/users/radius.md#adc-aa-radius)
- [LDAP](https://angie.software//adc/docs/getting-started/users/ldap.md#adc-aa-ldap)
- [TACACS+](https://angie.software//adc/docs/getting-started/users/tacacs.md#adc-aa-tacacs)
# https://angie.software/adc/docs/getting-started/users/ldap.md
# Подключение внешних пользователей через LDAP
Вы можете включить и настроить аутентификацию и авторизацию для внешних пользователей через LDAP.
Пользователям может быть назначена одна из следующих ролей:
- `Администратор`: обладает полными правами на все действия в системе;
- `Супервизор`: может только просматривать информацию в системе.
Роли внешних пользователей определяются на основе принадлежности к LDAP-группам.
Для подключения внешних пользователей к системе вам необходимо:
1. включить внешнюю аутентификацию через LDAP и задать настройки сервера;
2. включить внешнюю авторизацию через LDAP и задать настройки сервера;
3. задать базовый DN и фильтры для поиска пользователей и групп на LDAP-сервере;
4. настроить соответствие LDAP-групп и ролей пользователей в Angie ADC.
На стороне LDAP-сервера также должны быть настроены
пользователи, группы и сервисная учетная запись для Angie ADC.
#### WARNING
Необходимо настроить и включить оба блока: аутентификацию и авторизацию.
Если один из блоков не настроен или выключен,
внешние пользователи не смогут получить доступ к системе.
## Шаги
1. Откройте веб-интерфейс Angie ADC. В панели навигации перейдите в раздел
`Система` → `Аутентификация и авторизация`.
Откроется страница с настройками аутентификации и авторизации для внешних пользователей.
2. Включите переключатель `Включить внешнюю аутентификацию`
и выберите провайдера аутентификации LDAP.
#### NOTE
Одновременно поддерживается использование только одного провайдера внешней аутентификации.
При добавлении нового провайдера аутентификации настройки предыдущего провайдера сбрасываются.
3. Укажите следующие параметры:
- `Сервер`: IP-адрес или доменное имя LDAP-сервера.
- `Порт`: порт подключения к LDAP-серверу (по умолчанию `389`).
- `Режим защиты соединения` (по умолчанию `Без TLS`, также доступны варианты
`LDAPS` и `StartTLS` для защищенного соединения).
#### NOTE
При выборе режима защиты соединения `LDAPS` или `StartTLS`
становится доступен флажок `Проверять TLS-сертификат`.
По умолчанию флажок установлен.
- `DN сервисной учетной записи`: логин сервисной учетной записи,
от имени которой система подключается к LDAP.
- `Пароль сервисной учетной записи`: пароль сервисной учетной записи
для подключения к LDAP-серверу.
- `Базовый DN пользователей`: задает ветку на LDAP-сервере,
в которой система будет искать пользователя,
например `ou=users,dc=example,dc=com`.
- `Идентификатор логина`: поле в LDAP, которое содержит логин,
например `uid`, `sAMAccountName` или `userPrincipalName`.
- `Фильтр поиска`: LDAP-фильтр для поиска пользователя,
например `(&(objectClass=user)(sAMAccountName=%s))`.
#### NOTE
Фильтр LDAP определяет, в каком формате пользователь должен вводить логин
при входе в систему:
- если используется фильтр `(&(objectClass=user)(sAMAccountName=%s))`, то логин
будет без доменного имени, например `ivanov`;
- если используется фильтр `(&(objectClass=user)(userPrincipalName=%s)`,
то логин будет полным: `ivanov@domain.com`.
4. Нажмите `Сохранить`.
Внешняя аутентификация с использованием провайдера LDAP будет включена.
5. В блоке `Внешняя авторизация`
переведите переключатель `Включить внешнюю авторизацию`
в положение "включено" и выберите провайдера авторизации LDAP.
6. Задайте параметры подключения к серверу:
- `Сервер`: IP-адрес или доменное имя LDAP-сервера.
- `Порт`: порт подключения к LDAP-серверу (по умолчанию `389`).
7. Укажите параметры защиты соединения: `Без TLS` (по умолчанию)
или `TLS (LDAPS)`/ `startTLS`,
если необходимо использовать безопасное соединение при подключении к серверу.
#### NOTE
При выборе режима защиты соединения `LDAPS` или `StartTLS`
становится доступен флажок `Проверять TLS-сертификат`.
По умолчанию флажок установлен.
8. В блоке `Сервисная учетная запись (bind)` укажите DN учетной записи,
с которой будет выполняться подключение к LDAP-серверу.
Можно использовать учетную запись администратора LDAP-сервера,
например `cn=admin,dc=example,dc=com`.
9. Если требуется, установите флажок `Подключаться с паролем` и укажите пароль
сервисной учетной записи.
10. В блоке `Поиск и роли` укажите следующие параметры:
- `Базовый DN пользователей`, например `ou=users,dc=example,dc=com`;
- `Фильтр поиска пользователей`, например `(uid=%s)`;
- `Базовый DN групп`, например `ou=groups,dc=example,dc=com`;
- `Фильтр поиска групп`, например `(member=%s)`.
11. В блоке `Маппинг LDAP-групп и ролей` нажмите `Добавить правило`
и задайте соответствие LDAP-групп пользователей ролям в Angie ADC.
Например, если на LDAP-сервере для администраторов создана группа
`dn: cn=,ou=groups,dc=example,dc=com`, то
укажите значение `cn=,ou=groups,dc=example,dc=com`
в поле `DN группы`
и выберите роль `Администратор (admin)`.
12. Нажмите `Сохранить`.
Внешняя авторизация будет настроена и включена.
При входе внешнего пользователя в систему на LDAP-сервере будет
выполняться поиск групп, в которых он состоит.
Если найденные группы совпадают с группами, указанными в маппинге,
то пользователю будет назначена соответствующая роль.
Если пользователь не найден ни в одной из групп или
LDAP-группы недоступны или некорректны, доступ к системе будет запрещен.
# https://angie.software/adc/docs/getting-started/users/tacacs.md
# Подключение внешних пользователей через TACACS
Вы можете включить и настроить аутентификацию и авторизацию для внешних пользователей через TACACS.
Пользователям может быть назначена одна из следующих ролей:
- `Администратор`: обладает полными правами на все действия в системе;
- `Супервизор`: может только просматривать информацию в системе.
Роли для внешних пользователей определяются на основе соответствия
атрибутам этих пользователей в TACACS+.
Для подключения внешних пользователей к системе вам необходимо:
1. включить внешнюю аутентификацию через TACACS и задать настройки сервера;
2. включить внешнюю авторизацию через TACACS+ и задать настройки сервера;
3. настроить соответствие атрибутов TACACS+ ролям пользователей в Angie ADC.
На стороне TACACS-сервера также должны быть настроены
пользователи и группы.
Пример настройки:
```none
group = admin {
service = shell {
set priv-lvl = 15
}
}
user = admin {
password = clear admin
member = admin
}
```
#### WARNING
Необходимо настроить и включить оба блока: аутентификацию и авторизацию.
Если один из блоков не настроен или выключен,
внешние пользователи не смогут получить доступ к системе.
## Шаги
1. Откройте веб-интерфейс Angie ADC. В панели навигации перейдите в раздел
`Система` → `Аутентификация и авторизация`.
Откроется страница с настройками аутентификации и авторизации для внешних пользователей.
2. Включите переключатель `Включить внешнюю аутентификацию`
и выберите провайдера аутентификации TACACS.
#### NOTE
Одновременно поддерживается использование только одного провайдера внешней аутентификации.
При добавлении нового провайдера аутентификации настройки предыдущего провайдера сбрасываются.
3. Укажите следующие параметры:
- `Адрес`: IP-адрес или доменное имя TACACS-сервера.
- `Порт`: порт подключения к TACACS-серверу (по умолчанию `49`).
- `Секрет`: общий секрет для шифрования паролей.
4. Нажмите `Сохранить`.
Внешняя аутентификация с использованием провайдера TACACS будет включена.
5. В блоке `Внешняя авторизация`
переведите переключатель `Включить внешнюю авторизацию`
в положение "включено" и выберите провайдера авторизации TACACS.
6. Задайте параметры подключения к серверу:
- `Адрес`: IP-адрес или доменное имя TACACS-сервера.
- `Порт`: порт подключения к TACACS-серверу (по умолчанию `49`).
- `Секрет`: общий секрет для шифрования паролей.
7. Укажите в порядке приоритета атрибуты ролей пользователя в TACACS+,
например `priv-lvl`, затем `role`.
По этим атрибутам Angie ADC будет определять роль для пользователя.
8. Укажите, какой сервис и протокол будут использоваться
в запросе на авторизацию (AUTHOR).
Параметры зависят от выбранного сервера. Например, для TACACS+
рекомендуется указать `service=shell` и `protocol=ip`.
9. Задайте соответствие значений атрибутов TACACS+ ролям в Angie ADC,
например `priv-lvl=15` → `Администратор`
или `role=adc-admin` → `Администратор`.
10. Нажмите `Сохранить`.
Внешняя авторизация будет настроена и включена.
При входе внешнего пользователя в систему на TACACS-сервер будет
отправлен запрос на авторизацию.
Если атрибуты и значения в ответе TACACS совпадают с указанными в маппинге,
то пользователю будет назначена соответствующая роль в Angie ADC.
Если полученные данные не совпадают с указанными в маппинге или
TACACS-сервер недоступен, доступ к системе будет запрещен.
# https://angie.software/adc/docs/getting-started/users/radius.md
# Подключение внешних пользователей через RADIUS
Вы можете включить и настроить аутентификацию и авторизацию для внешних пользователей через RADIUS.
Пользователям может быть назначена одна из следующих ролей:
- `Администратор`: обладает полными правами на все действия в системе;
- `Супервизор`: может только просматривать информацию в системе.
Роли для внешних пользователей определяются на основе соответствия
атрибутам этих пользователей в RADIUS.
#### NOTE
RADIUS-авторизация доступна только при аутентификации через RADIUS.
Для подключения внешних пользователей к системе вам необходимо:
1. включить внешнюю аутентификацию через RADIUS и задать настройки сервера;
2. включить внешнюю авторизацию через RADIUS и задать настройки сервера;
3. настроить соответствие атрибутов RADIUS ролям пользователей в Angie ADC.
На стороне RADIUS-сервера также должны быть настроены
пользователи и их атрибуты.
Пример настройки:
```none
user1 Cleartext-Password := "P@ssword"
Filter-Id := "adc-admin",
Service-Type := Administrative-User,
Cisco-AVPair := "shell:priv-lvl=15",
Reply-Message := "Welcome, Admin",
Class := "AdminGroup",
Tunnel-Type := VLAN,
Tunnel-Medium-Type := IEEE-802,
Tunnel-Private-Group-ID := "100"
user2 Cleartext-Password := "P@ssword"
Filter-Id := "adc-readonly",
Service-Type := NAS-Prompt-User,
Cisco-AVPair := "shell:priv-lvl=7",
Reply-Message := "Welcome, Supervisor",
Class := "SupervisorGroup",
Tunnel-Type := VLAN,
Tunnel-Medium-Type := IEEE-802,
Tunnel-Private-Group-ID := "200"
```
#### WARNING
Необходимо настроить и включить оба блока: аутентификацию и авторизацию.
Если один из блоков не настроен или выключен,
внешние пользователи не смогут получить доступ к системе.
## Шаги
1. Откройте веб-интерфейс Angie ADC. В панели навигации перейдите в раздел
`Система` → `Аутентификация и авторизация`.
Откроется страница с настройками аутентификации и авторизации для внешних пользователей.
2. Включите переключатель `Включить внешнюю аутентификацию`
и выберите провайдера аутентификации RADIUS.
#### NOTE
Одновременно поддерживается использование только одного провайдера внешней аутентификации.
При добавлении нового провайдера аутентификации настройки предыдущего провайдера сбрасываются.
3. Укажите следующие параметры:
- `Сервер`: IP-адрес или доменное имя RADIUS-сервера.
- `Порт`: порт подключения к RADIUS-серверу (по умолчанию `1812`).
- `Протокол`: протокол передачи данных: `UDP`
или `TCP` (по умолчанию: `UDP`).
- `NAS-идентификатор`: идентификатор NAS (Network Access Server), передаваемый серверу RADIUS.
- `Метод аутентификации`: поддерживается только `PAP`.
- `Секрет`: общий секрет для шифрования паролей.
4. Нажмите `Сохранить`.
Внешняя аутентификация с использованием RADIUS будет включена.
5. В блоке `Внешняя авторизация`
переведите переключатель `Включить внешнюю авторизацию`
в положение "включено" и выберите провайдера авторизации RADIUS.
6. Укажите атрибут роли пользователя в RADIUS,
например `Filter-Id`, `vsa:9:1` или другой используемый атрибут.
По этому атрибуту Angie ADC будет определять роль для пользователя.
Допускается использование следующих атрибутов ролей:
- `Filter-Id` — роль пользователя.
- `Class` — группа, к которой относится пользователь.
- `Service-Type` — тип сервиса, по которому определяется роль пользователя
(Administrative, Login и др.)
- `Tunnel-Private-Group-ID` — VLAN ID (используется для VLAN-авторизации).
- `VSA` — Vendor-Specific в формате `vsa::`
(например `vsa:9:1`).
7. Задайте соответствие значений атрибутов RADIUS ролям в Angie ADC,
например для Filter-Id укажите `adc-admin` → `Администратор`,
а при использовании `vsa:9:1` укажите `shell:priv-lvl=15` → `Администратор`.
8. Нажмите `Сохранить`.
Внешняя авторизация через RADIUS будет настроена и включена.
При входе внешнего пользователя в систему через RADIUS
будут получены атрибуты его роли.
Если атрибуты и значения совпадают с указанными в маппинге,
то пользователю будет назначена соответствующая роль в Angie ADC.
Если данные не совпадают с указанными в маппинге или
RADIUS-сервер недоступен, доступ к системе будет запрещен.
# https://angie.software/adc/docs/load_balancer.md
# Балансировщик нагрузки
**Балансировка**
Балансировщик нагрузки позволяет распределять клиентские запросы по серверам
на основании выбранного алгоритма балансировки,
данных статистики или обратной связи от сервера (см. [Методы балансировки](https://angie.software//adc/docs/load_balancer/lb-methods.md#adc-load-balancing-methods)).
В идеале клиентские запросы равномерно распределяются по всем серверам,
что увеличивает совокупную производительность системы.
Доступна балансировка на двух уровнях: L7 (протокол HTTP) и L4 (TCP и UDP).
**Высокая доступность**
Высокая доступность системы обеспечивается за счет:
- [проверок работоспособности](https://angie.software//adc/docs/load_balancer/health-probes.md#adc-health-probes) апстрим-серверов;
- наличия spare-серверов, позволяющих плавно подхватывать трафик в рамках одной группы серверов без переключения;
- создания [дополнительных резервных групп серверов](https://angie.software//adc/docs/load_balancer/backup-server-groups.md#adc-multiple-backup-groups), обеспечивающих работу
при выходе из строя всех серверов в основной группе.
**Дополнительная настройка**
Помимо алгоритмов распределения запросов,
в HTTP- и TCP/UDP-балансировке могут использоваться смежные модули:
- Модуль `queue` создает очередь запросов. Если балансировщик не смог выбрать апстрим-сервер для обработки,
то запрос попадает в очередь ожидания.
- Модуль `keepalive` позволяет держать открытые неактивные соединения с апстрим-серверами,
т. е. не закрывать соединения при завершении обработки запроса.
- Директива `bind_conn`, реализованная в модуле `keepalive`, позволяет привязать
клиентское соединение к серверному соединению.
- Модуль `sticky` также позволяет привязывать клиентское соединение к апстрим-серверу,
но на основе информации, содержащейся в самом запросе.
- Модуль `zone` обеспечивает доступ с использованием REST API.
API позволяет получать набор метрик, в том числе относящихся к балансировке.
- Модуль `upstream_probe` позволяет обеспечить активные проверки апстрим-серверов.
Подробнее см. [в справочнике HTTP-модуля](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-http-upstream)
и [в справочнике потокового модуля](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-stream-upstream).
**Хранение версий конфигурации**
Все версии конфигурации балансировщика нагрузки сохраняются.
Вы можете просмотреть историю изменений,
а также [восстановить конфигурацию](https://angie.software//adc/docs/load_balancer/config-backup.md#adc-backups) из резервной копии.
**Справочная информация**
В разделе [Справочная информация](https://angie.software//adc/docs/load_balancer/reference/index.md#adc-reference) представлены сведения о встроенных и сторонних модулях,
примеры их настройки, а также поддерживаемые ими директивы и переменные.
В этом разделе:
- [Методы балансировки](https://angie.software//adc/docs/load_balancer/lb-methods.md#adc-load-balancing-methods)
- [Проверки работоспособности серверов](https://angie.software//adc/docs/load_balancer/health-probes.md#adc-health-probes)
- [Резервирование проксируемых серверов](https://angie.software//adc/docs/load_balancer/backup-server-groups.md#adc-multiple-backup-groups)
- [Настройка конфигурации](https://angie.software//adc/docs/load_balancer/config.md#adc-load-balancer-config)
- [Резервное копирование и восстановление конфигурации](https://angie.software//adc/docs/load_balancer/config-backup.md#adc-backups)
- [Загрузка и раздача статических файлов](https://angie.software//adc/docs/load_balancer/static.md#adc-static)
- [Справочная информация](https://angie.software//adc/docs/load_balancer/reference/index.md#adc-reference)
# https://angie.software/adc/docs/load_balancer/config.md
# Настройка конфигурации
Для настройки балансировщика нагрузки используется декларативная конфигурация.
Конфигурацию балансировщика нагрузки можно просмотреть и отредактировать
в веб-интерфейсе Angie ADC
(`Управление трафиком` → `Балансировщик нагрузки`).
## Структура конфигурации
Балансировщик нагрузки состоит из модулей, которые настраиваются директивами,
заданными в конфигурации.
Директивы могут быть простыми и блочными.
Простая директива состоит из имени и параметров, разделенных пробелами,
и оканчивается точкой с запятой `;`.
В блочной директиве вместо точки с запятой после имени и параметров следует
набор дополнительных инструкций внутри фигурных скобок `{` и `}`.
Блочные директивы называются контекстами.
Примеры:
- контекст [events](https://angie.software//adc/docs/load_balancer/reference/core.md#adc-events) (общая обработка соединений);
- контекст [http](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-http-core) (конфигурация HTTP-балансировки);
- контекст [stream](https://angie.software//adc/docs/load_balancer/reference/stream/stream.md#adc-stream-core) (конфигурация TCP/UDP балансировки).
Контексты `events`, `http`, `stream` располагаются в контексте [main](https://angie.software//adc/docs/load_balancer/reference/core.md#adc-core).
Другие директивы, размещенные вне контекстов `events`, `http`, `stream`,
считаются также находящимися в контексте `main`.
В контекстах [http](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-http-core) и [stream](https://angie.software//adc/docs/load_balancer/reference/stream/stream.md#adc-stream-core) размещаются:
- блоки `server`, в которых настраивается проксирование трафика;
- блоки `upstream`, в которых настраиваются группы upstream-серверов
для балансировки нагрузки.
В конфигурации в веб-интерфейсе Angie ADC уже предустановлены некоторые общие параметры.
Вам необходимо дополнить конфигурацию с учетом ваших целей.
Подробнее о конфигурации и обработке соединений
см. [Конфигурационные файлы](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) и [Соединения, сессии, запросы, логи](https://angie.software//adc/docs/load_balancer/reference/processing.md#adc-processing).
#### IMPORTANT
Строки конфигурации, приведенные ниже, нельзя удалять или менять
(они используются для обеспечения работы соответствующего функционала Angie ADC).
Контекст `main`:
```nginx
error_log /var/log/angie-lb/healthmonitoring.log error;
pid /run/angie-lb.pid;
```
Контекст `http`:
```nginx
include /etc/angie-lb/prometheus_all.conf;
include /etc/angie-lb/internal/prometheus.conf;
```
## Использование портов
Если вы планируете использовать в конфигурации другие порты помимо 80/443,
вы можете открыть их с помощью команды [open](https://angie.software//adc/docs/management/cli-commands.md#adc-cli-firewall-open) через CLI Angie ADC.
#### IMPORTANT
При настройке конфигурации не занимайте следующие порты
(используются внутренними сервисами Angie ADC):
TCP:
22, 199, 2022, 2222, 2601, 2602, 2603, 2604, 2605, 2606,
2615, 2616, 2617, 2619, 2623, 3050, 3051, 3053, 3054, 3060,
3111, 3122, 3123, 3301, 3302, 3380, 3391, 5044, 5355, 5432,
8010, 8080, 9090, 9100, 9120, 9600, 9633, 9898, 9900, 60080
* Порты 8080 и 8443 можно использовать, если у вас выделен отдельный [интерфейс управления](https://angie.software//adc/docs/getting-started/setup-wizard.md#adc-frw-mgmt).
UDP:
53, 161, 323, 546, 3784, 3785, 4784, 5355, 7784
## Настройка простого прокси-сервера
Angie ADC можно использовать в качестве прокси-сервера, который принимает запросы,
перенаправляет их на проксируемые серверы, получает от них ответы и отправляет их клиенту.
В примере ниже настраивается базовый прокси-сервер,
который будет обслуживать запросы изображений из локального каталога
и отправлять все остальные запросы на проксируемый сервер.
1. Создайте сервер, который будет использоваться в качестве бэкенда для прокси
(проксируемый сервер ), добавив блок `server` в контекст `http`:
```nginx
server {
listen 8081;
root /static/www;
location / {
}
}
```
Здесь сервер слушает на порту `8081` и сопоставляет URI запросов
с файлами в каталоге `/static/www` (как настроить загрузку и раздачу
статических файлов см. соотв. статью). Директива [root](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-root)
находится в контексте `server` и будет использоваться,
если директива [location](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-location),
выбранная для выполнения запроса, не содержит собственной директивы `root`.
#### NOTE
В общем случае конфигурационный файл может содержать несколько блоков `server`,
отличающихся портами, на которых они слушают ([listen](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-listen)),
и именами сервера ([server_name](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-server-name)).
Определив, какой `server` будет обрабатывать запрос, Angie ADC сравнивает
URI запроса с параметрами [location](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-location),
заданными в блоке `server`, и принимает решение.
2. Добавьте конфигурацию прокси-сервера:
```nginx
server {
listen 80;
location / {
proxy_pass http://localhost:8081/;
}
location ~ \.(gif|jpg|png)$ {
root /static/images;
}
}
```
В первом блоке `location` добавлена директива [proxy_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-pass)
c указанием протокола, имени и порта проксируемого сервера.
Во втором блоке `location` задано регулярное выражение
для всех URI, оканчивающихся на `.gif`, `.jpg` или `.png`.
Соответствующие запросы будут обслуживаться из каталога `/static/images`.
#### NOTE
При выборе блока `location`, который будет обслуживать запрос,
сначала проверяются директивы `location`, задающие префиксы, и
запоминается `location` с самым длинным подходящим префиксом.
Затем проверяются блоки `location`, заданные регулярными выражениями,
в порядке их объявления в конфигурации и используется первое совпадение.
Иначе берется `location`, сохраненный до этого.
3. Сохраните изменения в конфигурации, нажав на кнопку `Сохранить`.
Получившийся прокси-сервер будет обслуживать запросы
к файлам `.gif`, `.jpg` или `.png` из каталога `/static/images`,
а все остальные запросы будет проксировать на сервер `localhost:8081`.
## Настройка балансировки нагрузки
Чтобы настроить балансировку нагрузки для HTTP-трафика, добавьте
блок [upstream](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-http-upstream) в контекст `http`
и укажите в нем бэкенд-серверы, которые будут использоваться для балансировки нагрузки.
Затем настройте проксирование запросов на эту группу серверов
в блоке `server` с помощью директивы [location](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-location).
Пример:
```nginx
upstream backend {
zone backend 1m;
server backend1.example.com;
server backend2.example.com;
}
server {
listen 80;
server_name localhost;
location /api {
proxy_pass http://backend;
}
}
```
В приведенном примере задана группа серверов `backend`.
Все запросы на порт `80` с URI, начинающимися с `/api`,
проксируются в эту группу.
Метод балансировки нагрузки не указан явно,
поэтому по умолчанию используется метод `round-robin`
(запросы распределяются по серверам последовательно).
## Раширенная настройка
Дополнительно в конфигурации вы можете настроить:
- [метод балансировки](https://angie.software//adc/docs/load_balancer/lb-methods.md#adc-load-balancing-methods);
- [проверки работоспособности](https://angie.software//adc/docs/load_balancer/health-probes.md#adc-health-probes);
- [резервирование серверов и групп](https://angie.software//adc/docs/load_balancer/backup-server-groups.md#adc-multiple-backup-groups) для отказоустойчивости;
- смежные модули для HTTP-балансировки ([keepalive](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-u-keepalive),
[sticky](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-u-sticky), [zone](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-u-zone), [queue](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-u-queue))
и stream-балансировки ([sticky](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-s-u-sticky), [zone](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-s-u-zone)).
Подробнее см. [в справочнике HTTP-модуля](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-http-upstream)
и [в справочнике потокового модуля](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-stream-upstream).
# https://angie.software/adc/docs/load_balancer/lb-methods.md
# Методы балансировки
#### NOTE
Для каждой upstream-группы можно задать только один метод балансировки.
| Алгоритм | Описание | HTTP | TCP/UDP |
|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|-----------|
| `round-robin` | Запросы распределяются по серверам последовательно (используется по умолчанию).
Поддерживается учет веса серверов (`weight`), медленный старт (`slow_start`),
backup-группы серверов. | | |
| `hash` | Задает метод балансировки нагрузки для группы, при котором соответствие клиента серверу
определяется при помощи хэшированного значения ключа.
Поддерживается учет веса серверов (`weight`).
Подробнее см. [TCP/UDP](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-s-u-hash), [HTTP](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-u-hash). | | |
| `ip_hash` | Сервер выбирается с помощью хэш-функции на основе IP-адреса клиента,
что обеспечивает "липкость сессии". Частный случай `hash`.
В качестве ключа для хэширования
используются первые три октета IPv4-адреса клиента или IPv6-адрес клиента целиком.
В итоге запрос конкретного клиента всегда попадает на один и тот же сервер, если он работоспособен.
Поддерживается учет веса серверов (`weight`).
Подробнее см. [HTTP](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-u-ip-hash). | | |
| `least_conn` | Новый запрос направляется на сервер с минимальным количеством активных соединений (наименее загруженный).
Поддерживается учет веса серверов (`weight`), медленный старт (`slow_start`),
backup-группы серверов.
Подробнее см. [TCP/UDP](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-s-u-least-conn), [HTTP](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-u-least-conn). | | |
| `random` | Запросы распределяются по серверам случайным образом.
При большом числе запросов они будут распределяться по upstream-серверам равномерно,
что хорошо подходит, например, для кластера балансировщиков.
Поддерживается учет веса серверов (`weight`) и опциональный параметр `two`
(выбор из двух случайных серверов по `least_conn`).
Подробнее см. [TCP/UDP](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-s-u-random), [HTTP](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-u-random). | | |
| `least_time` | Балансировка нагрузки на основе наименьшего времени ответа.
Запросы распределяются на те серверы, которые обрабатывают их быстрее.
Уменьшает время ожидания для пользователей.
Если серверы имеют разное оборудование или настройки,
помогает уравновесить нагрузку.
Поддерживаются backup-группы серверов.
Подробнее см. [TCP/UDP](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-s-u-least-time), [HTTP](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-u-least-time). | | |
| `feedback` | Балансировка нагрузки по обратной связи (по произвольному параметру из ответа на основной или проверочный запрос).
Поддерживается учет веса серверов (`weight`), медленный старт (`slow_start`),
backup-группы серверов.
Подробнее см. [TCP/UDP](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-s-u-feedback), [HTTP](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-u-feedback). | | |
| `least_bandwidth` | Балансировка на основе наименьшего потребления полосы пропускания.
Режимы: upstream, downstream, both.
Поддерживается учет веса серверов (`weight`), медленный старт (`slow_start`),
backup-группы серверов.
Подробнее см. [TCP/UDP](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-s-u-least-bandwidth), [HTTP](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-u-least-bandwidth). | | |
| `least_packets` | Балансировка на основе наименьшего числа пакетов в единицу времени.
Может использоваться в случаях, когда оборудование, расположенное за балансировщиком,
не способно "переварить" слишком большой поток пакетов. Режимы: upstream, downstream, both.
Поддерживается учет веса серверов (`weight`), медленный старт (`slow_start`),
backup-группы серверов.
Подробнее см. [TCP/UDP](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-s-u-least-packets). | | |
## Примеры HTTP-балансировки нагрузки
### Базовая настройка
Самая простая конфигурация для балансировки нагрузки с помощью Angie ADC может выглядеть следующим образом:
```nginx
http {
upstream myapp1 {
server srv1.example.com;
server srv2.example.com;
server srv3.example.com;
}
server {
listen 80;
location / {
proxy_pass http://myapp1;
}
}
}
```
В приведенном примере:
- Группа серверов `myapp1` содержит три сервера `srv1`, `srv2` и `srv3`.
- На этих серверах работают три экземпляра одного и того же приложения.
- Используется метод балансировки `round-robin` (по умолчанию).
- Все запросы на порт `80` перенаправляются через группу серверов `myapp1`.
### least_conn
Балансировка нагрузки по наименее загруженному серверу.
Модуль балансировки нагрузки `least_conn` в модуле HTTP позволяет распределять нагрузку более равномерно, направляя новые запросы на серверы с наименьшим количеством активных соединений. Этот метод рекомендуется, если время обработки запросов может сильно варьироваться.
Пример конфигурации:
```nginx
http {
upstream backend {
least_conn;
server backend1.example.com;
server backend2.example.com;
server backend3.example.com;
}
server {
listen 80;
location / {
proxy_pass http://backend;
}
}
}
```
В этом примере:
- Директива `least_conn` включает метод балансировки нагрузки по наименьшему
числу соединений.
- Для балансировки нагрузки определены три проксируемых сервера.
- Входящие запросы к серверу проксируются в группу `backend`.
Преимущества метода:
- Динамическая балансировка: непрерывно отслеживает количество
активных соединений для адаптации к текущей нагрузке на каждом сервере.
- Простота: работает без необходимости дополнительных параметров или сложных
настроек.
- Совместимость: совместим с другими конфигурациями проксируемых серверов,
включая веса, максимальное количество сбоев и время ожидания после сбоя.
### ip_hash
Балансировка нагрузки с сохранением сессий.
Методы `round-robin` и `least-conn` не гарантируют, что запросы от одного клиента будут обрабатываться одним и тем же сервером. Если важно, чтобы клиент всегда направлялся на один сервер (например, при использовании сессионных данных), можно использовать метод `ip_hash`.
Пример конфигурации:
```nginx
upstream myapp1 {
ip_hash;
server srv1.example.com;
server srv2.example.com;
server srv3.example.com;
}
```
Метод `ip_hash` гарантирует, что запросы от одного клиента будут попадать на один сервер, если этот сервер доступен.
### weight
Взвешенная балансировка нагрузки.
С помощью директивы `weight` можно указать, какой сервер должен обрабатывать больше запросов. Этот способ рекомендуется, если серверы имеют разную производительность. По умолчанию вес сервера равен `1`.
Пример:
```nginx
upstream myapp1 {
server srv1.example.com weight=3;
server srv2.example.com;
server srv3.example.com;
}
```
В этой конфигурации каждые пять запросов будут распределены следующим образом:
три запроса попадут на `srv1`, один запрос — на `srv2` и еще один — на `srv3`.
Метод `weight` может использоваться в комбинации с методами `round-robin` и `least-conn`.
### least_time
Балансировка нагрузки на основе наименьшего времени ответа.
Модуль балансировки нагрузки `least_time` задает для группы метод балансировки нагрузки, при котором вероятность передачи соединения активному серверу обратно пропорциональна среднему времени его ответа; чем оно меньше, тем больше соединений будет получать сервер.
Когда использовать `least_time`?
- Переменная нагрузка: запросы распределяются на серверы, которые обрабатывают их быстрее.
- Высокая доступность: уменьшается время ожидания для пользователей.
- Гетерогенные серверы: если серверы имеют разное оборудование или настройки, `least_time` помогает уравновесить нагрузку.
Пример конфигурации:
```nginx
http {
upstream backend {
least_time header;
server backend1.example.com;
server backend2.example.com;
server backend3.example.com;
}
server {
listen 80;
location / {
proxy_pass http://backend;
}
}
}
```
В этом примере `least_time header`: балансировка основана на времени отклика до получения заголовка ответа от сервера.
### feedback
Балансировка по произвольному параметру из ответа на основной или проверочный запрос.
Модуль балансировки нагрузки `feedback` Задает в `upstream` механизм балансировки нагрузки по обратной связи. Он динамически корректирует решения при балансировке, умножая вес каждого проксируемого сервера на среднее значение обратной связи, которое меняется с течением времени в зависимости от значения переменной и подчиняется необязательному условию. По умолчанию параметр `factor` равен `90`.
Пример конфигурации:
```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`,
чтобы учитывать только ответы от активной проверки `high_priority`
или ответы на обычные клиентские запросы.
## Примеры TCP/UDP-балансировки нагрузки
### Конфигурация для TCP
```nginx
stream {
upstream tcp_backend {
server 192.168.1.10:3306 weight=2;
server 192.168.1.11:3306;
server 192.168.1.12:3306;
}
server {
listen 3306;
proxy_pass tcp_backend;
proxy_timeout 10s;
proxy_connect_timeout 5s;
}
}
```
В этой конфигурации задана группа серверов, участвующих в балансировке (`tcp_backend`).
Настроен вес для серверов, чтобы более мощный сервер получал больше запросов (`weight=2`),
Сервер слушает входящие соединения на порту `3306` (используется для MySQL).
Трафик перенаправляется к группе серверов `tcp_backend`.
Настроены тайм-ауты:
- максимальное время ожидания ответа от сервера `10s`;
- максимальное время для установления соединения с сервером `5s`.
### Конфигурация для UDP
Для приложений, работающих через протокол UDP, конфигурация аналогична TCP, но с настройками для UDP-трафика.
```nginx
stream {
upstream udp_backend {
server 192.168.1.20:53;
server 192.168.1.21:53;
}
server {
listen 53 udp;
proxy_pass udp_backend;
proxy_responses 1;
proxy_timeout 10s;
}
}
```
### least_bandwidth
Балансировка на основе наименьшего потребления полосы пропускания.
Алгоритм периодически вычисляет среднее использование полосы пропускания для каждого апстрим-сервера, используя формулу скользящего среднего для сглаживания колебаний со временем.
Когда начинается новая сессия,
модуль балансировки нагрузки `least_bandwidth` выбирает проксируемый сервер
с наименьшим средним использованием пропускной способности, скорректированным с учетом веса сервера, если он указан.
Этот механизм гарантирует, что сессии направляются на серверы,
которые в настоящее время используют меньше пропускной способности,
что способствует равномерному распределению сетевой нагрузки.
Пример конфигурации:
```nginx
stream {
upstream backend {
least_bandwidth both factor=80;
server backend1.example.com:12345;
server backend2.example.com:12345;
}
server {
listen 12345;
proxy_pass backend;
}
}
```
В этом примере:
- В директиве `least_bandwidth` настроен учет как входящей, так и исходящей
пропускной способности.
- Коэффициент сглаживания установлен равным 80, что влияет на скорость адаптации
среднего значения к изменениям в использовании пропускной способности.
- Для балансировки нагрузки определены два проксируемых сервера.
Преимущества метода:
- Динамическая балансировка: непрерывно отслеживает использование
пропускной способности для адаптации к текущей нагрузке на каждом сервере.
- Коэффициент сглаживания `factor` контролирует отзывчивость
расчета скользящего среднего; более высокий коэффициент означает более
медленную адаптацию к изменениям.
- Режимы: позволяет выбирать балансировку на основе входящей пропускной
способности, исходящей пропускной способности или обоих вариантов, в зависимости от
потребностей приложения.
- Совместим с другими конфигурациями проксируемых серверов,
включая веса, максимальное количество сбоев и время ожидания после сбоя.
### least_packets
Балансировка на основе наименьшего числа пакетов в единицу времени.
Средняя скорость пакетов для каждого проксируемого сервера периодически проверяется
с использованием формулы скользящего среднего для сглаживания колебаний со временем.
Когда инициируется новый сеанс, модуль балансировки нагрузки `least_packets`
в потоковом модуле выбирает проксируемый сервер с наименьшей средней скоростью передачи пакетов,
скорректированной с учетом веса сервера.
Этот процесс гарантирует, что сеансы направляются на серверы, которые в настоящее время наименее загружены
с точки зрения обработки пакетов, что способствует равномерному распределению сетевой нагрузки.
Пример конфигурации:
```nginx
stream {
upstream backend {
least_packets both factor=80;
server backend1.example.com:12345;
server backend2.example.com:12345;
}
server {
listen 12345;
proxy_pass backend;
}
}
```
В этом примере:
- В директиве `least_packets` настроен учет как входящих, так и исходящих
пакетов.
- Коэффициент сглаживания установлен равным 80, что влияет на то, как быстро
среднее значение адаптируется к изменениям скорости пакетов.
- Определены два проксируемых сервера для балансировки нагрузки.
Преимущества метода:
- Динамическая балансировка: непрерывно отслеживает скорость
пакетов для адаптации к текущей нагрузке на каждом сервере.
- Параметр `factor` контролирует отзывчивость
расчета скользящего среднего; более высокий коэффициент означает более
медленную адаптацию к изменениям.
- Режимы: позволяет выбирать балансировку на основе числа входящих пакетов,
исходящих пакетов или обоих значений.
- Совместим с другими конфигурациями проксируемых серверов,
включая веса, максимальное количество сбоев и время ожидания после сбоя.
### hash
Контекстное хэширование.
Поддерживается метод `hash` (например, по IP или произвольному значению). Если сервер из пула станет недоступным или будет добавлен новый сервер, минимальное количество клиентов перенаправится на другие серверы. Используется для "липких сессий", когда важно, чтобы запросы от одного клиента всегда обрабатывались одним и тем же сервером.
Пример:
```nginx
upstream tcp_backend {
hash $remote_addr consistent;
server 192.168.1.10:3306;
server 192.168.1.11:3306;
}
```
### Ограничение IP
Для защиты можно использовать ограничения IP через `allow` и `deny`.
Пример:
```nginx
server {
listen 3306;
allow 192.168.1.0/24;
deny all;
proxy_pass tcp_backend;
}
```
В этом примере разрешена только локальная сеть, остальным доступ запрещен.
# https://angie.software/adc/docs/load_balancer/health-probes.md
# Проверки работоспособности серверов
Angie ADC включает пассивные и активные проверки работоспособности серверов (health probes). Если сервер начинает отвечать с ошибками, Angie ADC временно исключает его из пула доступных серверов.
## Пассивные проверки
Пассивные проверки работают автоматически на основе реальных клиентских запросов.
Пример:
```nginx
upstream myapp1 {
server srv1.example.com max_fails=2 fail_timeout=10s;
server srv2.example.com;
server srv3.example.com;
}
```
В этой конфигурации сервер помечается как недоступный после двух неудачных запросов подряд (`max_fails=2`).
Через десять секунд сервер снова проверяется на доступность (`fail_timeout=10s`).
Если он восстановился, запросы снова начинают отправляться на этот сервер.
## Активные проверки
Активные проверки позволяют оценить доступность сервера без участия клиентов.
Поддерживаются активные проверки для HTTP и TCP / UDP.
Проверки задаются с помощью директивы `upstream_probe`.
Для одного апстрима можно определить несколько проверок.
Можно гибко настраивать поведение проверок. Поддерживается отправка ICMP echo-запросов (ping).
Подробнее см. справочные материалы по активным проверкам [HTTP](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream_probe.md#adc-http-upstream-probe)
и [stream](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream_probe.md#adc-stream-upstream-probe).
### Пример для HTTP
```nginx
upstream backend {
zone backend 1m;
server backend1.example.com;
server backend2.example.com;
}
map $upstream_status $good {
200 "1";
}
server {
listen ...;
location /backend {
...
proxy_pass http://backend;
upstream_probe backend_probe
uri=/probe
port=10004
interval=5s
test=$good
essential
persistent
fails=3
passes=3
max_body=10m
mode=idle;
}
}
```
Детали работы:
- Изначально сервер не получает клиентские запросы,
пока не пройдет *все* заданные для него проверки с параметром `essential`
(пропуская помеченные как `persistent`, если конфигурация перезагружена
и до этого сервер считался работающим).
Если таких проверок нет, сервер считается работающим.
- Сервер считается неработающим и не получает клиентские запросы,
если *какая-либо* заданная для него проверка достигает своего порога `fails`
или сам сервер достигает порога [max_fails](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-max-fails).
- Чтобы неработающий сервер снова мог считаться работающим,
*все* заданные для него проверки должны достичь своего порога `passes`;
после этого учитывается порог [max_fails](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-max-fails).
### Пример для TCP/UDP
```nginx
upstream backend {
zone backend 1m;
server a.example.com;
server b.example.com;
}
map $upstream_probe_response $good {
~200 "1";
default "";
}
server {
listen ...;
# ...
proxy_pass backend;
upstream_probe_timeout 1s;
upstream_probe backend_probe
port=12345
interval=5s
test=$good
essential
persistent
fails=3
passes=3
max_response=512k
mode=onfail
"send=data:GET / HTTP/1.0\r\n\r\n";
}
```
#### NOTE
Согласно спецификации RFC 2616 (HTTP/1.1) и RFC 9110 (HTTP Semantics),
заголовки HTTP должны разделяться последовательностью CRLF (`\r\n`), а
не просто `\n`.
Детали работы:
- Изначально сервер не получает клиентские запросы,
пока не пройдет *все* заданные для него проверки с параметром `essential`
(пропуская помеченные как `persistent`, если конфигурация перезагружена
и до этого сервер считался работающим).
Если таких проверок нет, сервер считается работающим.
- Сервер считается неработающим и не получает клиентские запросы,
если *какая-либо* заданная для него проверка достигает своего порога `fails`
или сам сервер достигает порога [max_fails](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-s-max-fails).
- Чтобы неработающий сервер снова мог считаться работающим,
*все* заданные для него проверки должны достичь своего порога `passes`;
после этого учитывается порог [max_fails](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-s-max-fails).
- Параметр `send` - отправляемые для проверки данные,
а переменная `$upstream_probe_response` – ответ бекенда.
### Пример ICMP echo-запроса для HTTP
```nginx
http {
upstream u {
zone z 1k;
server 127.0.0.1:8081;
server 127.0.0.1:8082;
}
server {
listen ...;
location / {
proxy_pass http://u/;
upstream_probe simple1
interval=3s
ping;
upstream_probe simple2
interval=3s
ping ping_timeout=3s;
}
}
}
```
Детали работы:
- Используется проверка методом ICMP Echo вместо HTTP-запроса.
- ICMP-проверка проверяет доступность IP-адреса `127.0.0.1`.
Порты `upstream` игнорируются.
- Сервер считается неработающим и не получает клиентские запросы, если не отвечает
на запрос ICMP Echo в течение заданного таймаута.
Первая проверка использует таймаут ожидания по умолчанию (1 секунда).
Вторая проверка задает таймаут ожидания ответа явно (3 секунды).
- Единственным критерием прохождения проверки является успешное получение ICMP-ответа в пределах таймаута.
# https://angie.software/adc/docs/load_balancer/backup-server-groups.md
# Резервирование проксируемых серверов
В Angie ADC поддерживаются:
- backup-группы серверов для многоуровневого резервирования
(при отказе всех серверов активной группы происходит переключение на backup-группу).
## Backup-серверы
Уровень резервирования backup-группы можно задать с помощью директивы `backup=n`
в блоках `stream` и `http`.
Например `backup=1` (или просто `backup`) — группа резервных серверов первого уровня,
(в API отображается как `true`), `backup=2` — группа резервных серверов второго уровня,
(в API отображается как соответствующее число).
Для SRV-записей уровень резервирования группы можно задать двумя способами:
- С помощью директивы `backup=prio` как абсолютное значение.
В этом случае значение приоритета `priority=n` из SRV-записи будет использовано
в качестве уровня резервной группы: `backup=n`.
- Через относительное значение приоритета `priority=n` из SRV-записи.
В этом случае директива `backup=n` задает базовый уровень отсчета (например `backup=3`),
а относительные уровни резервирования отсчитываются от этого уровня.
Сервер с наименьшим значением `priority` получит уровень `backup=3`,
следующий за ним — `backup=4` и так далее. Если уровень отсчета `backup=n` не задан,
отсчет будет идти от нуля: сервер с наименьшим значением `priority`
получит `backup=0` и станет основным, за ним — `backup=1`, резервный, и так далее.
Директива `backup_switch permanent` дает возможность
backup-группе проксируемых HTTP-серверов
оставаться активной, когда серверы из основной группы стали снова доступными.
Например, вы можете указать `permanent=2m`,
чтобы балансировщик нагрузки не пытался вернуться на основную группу чаще, чем раз в две минуты.
Если указать параметр `permanent` без значения, то балансировщик нагрузки не будет пытаться
вернуться на основную группу после перехода на резервную.
Функциональность `backup_switch permanent` реализована для `http` и `stream`.
Пример:
```nginx
upstream my_backend {
server primary1.example.com;
server primary2.example.com;
server backend.example.com service=http resolve backup=prio;
server backup1a.example.com backup;
server backup1b.example.com backup;
server backup2a.example.com backup=2;
server backup2b.example.com backup=2;
backup_switch permanent=2m;
}
```
# https://angie.software/adc/docs/load_balancer/config-backup.md
# Резервное копирование и восстановление конфигурации
В Angie ADC реализовано резервное копирование и хранение
всех версий конфигурационного файла балансировщика нагрузки.
При сохранении изменений в текущей конфигурации балансировщика
Angie ADC автоматически применяет ее и сохраняет предыдущую версию в репозитории.
Вы можете использовать [внутренний или внешний репозиторий](https://angie.software//adc/docs/management/system/backup-repo.md#adc-backup-repo).
Можно просмотреть список сохраненных версий конфигурационных файлов и применить нужную версию.
## Просмотр списка сохраненных конфигураций
Чтобы просмотреть список сохраненных конфигураций:
1. Откройте веб-интерфейс Angie ADC.
2. Выберите `Управление трафиком` → `Балансировщик нагрузки`
→ `История`.
Откроется таблица со списком сохраненных конфигурационных файлов.
Для каждого файла указано время его создания, версия Angie ADC,
статус (рабочая или нерабочая конфигурация), пользовательский комментарий,
теги (`angie-lb` и UUID) и дата последнего изменения.
## Изменение рабочего статуса конфигурации
Чтобы пометить конфигурацию как рабочую или нерабочую:
1. Откройте веб-интерфейс Angie ADC.
2. Выберите `Управление трафиком` → `Балансировщик нагрузки`
→ `История`.
Откроется таблица со списком сохраненных конфигурационных файлов.
3. Щелкните многоточие (`...`) напротив конфигурации, статус которой вы хотите изменить,
и нажмите `Пометить как нерабочую` или `Пометить как рабочую`.
4. Если вы устанавливаете нерабочий статус, укажите причину поломки и нажмите `Сохранить`.
Статус конфигурации будет изменен.
## Восстановление последней рабочей версии конфигурации
Чтобы применить последнюю рабочую версию конфигурации:
1. Откройте веб-интерфейс Angie ADC.
2. Выберите `Управление трафиком` → `Балансировщик нагрузки`
→ `История`.
3. В верхней части экрана нажмите кнопку `Применить последнюю рабочую версию`.
Будет применена последняя рабочая конфигурация.
## Восстановление конфигурации из резервной копии
Чтобы применить произвольную конфигурацию из резервной копии:
1. Откройте веб-интерфейс Angie ADC.
2. Выберите `Управление трафиком` → `Балансировщик нагрузки`
→ `История`.
Откроется таблица со списком сохраненных конфигурационных файлов.
3. Щелкните многоточие (`...`) напротив конфигурации, которую вы хотите использовать,
и нажмите кнопку `Применить`.
Конфигурация будет применена сразу.
# https://angie.software/adc/docs/load_balancer/static.md
# Загрузка и раздача статических файлов
Angie ADC поддерживает загрузку и раздачу статических файлов
(изображений, статических HTML-страниц и пр.).
Загрузка осуществляется по протоколу SCP (Secure Copy Protocol),
после чего файл будет доступен по HTTP.
Чтобы добавить статический файл, выполните следующие действия:
1. На машине-источнике запустите загрузку файла
(например страницу-заглушку `maintenance.html`):
```console
scp -P 2222 maintenance.html admin@<имя_хоста>:/maintenance.html
```
2. В веб-интерфейсе Angie ADC перейдите к редактированию конфигурации
балансировщика нагрузки (`Управление трафиком` → `Балансировщик нагрузки`)
и в блоке `http` настройте доступ к каталогу с этим файлом:
```nginx
http {
server {
listen 80;
root /var/transfer;
}
}
```
3. Если для расширения файла не определен MIME-тип или требуется указать его явно,
добавьте соответствующую строку в блок `types`
(например `application/pkix-crl crl;` для CRL).
4. Сохраните изменения, нажав кнопку `Сохранить`.
Файл `maintenance.html` будет доступен по адресу
`http://<имя_хоста>/maintenance.html`.
Чтобы проверить, что файл корректно отдается клиентам,
выполните запрос `curl`.
Например, для хоста `adc.angie.local`:
```console
$ curl adc.angie.local/maintenance.html -v
```
Если получен код `200 OK` и указан правильный Content-Type,
то файл был успешно загружен и доступен.
## Раздача файлов из разных локальных каталогов
В зависимости от типа файлы могут раздаваться из разных каталогов,
например HTML-страницы из `/static/www`, а изображения из `/static/images`.
Для настройки используется директива [location](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-location).
Чтобы настроить раздачу файлов из разных локальных каталогов,
выполните следующие действия:
1. Создайте локальный каталог со всеми необходимыми подкаталогами.
Например:
```console
mkdir -p static/www static/images
```
2. Перенесите в этот каталог статические файлы.
Например, поместите файл `index.html` в `/static/www`,
а изображение `image1.png` в `/static/images`.
3. Скопируйте весь каталог в файловое хранилище Angie ADC по SCP:
```console
scp -P 2222 -r static admin@<имя_хоста>:/
```
4. В веб-интерфейсе Angie ADC перейдите к редактированию конфигурации
балансировщика нагрузки (`Управление трафиком` → `Балансировщик нагрузки`)
и в блоке `http` настройте доступ к каталогам со статическими файлами:
```nginx
server {
location / {
root /static/www;
}
location /images/ {
root /static;
}
}
```
5. Сохраните изменения, нажав кнопку `Сохранить`.
Теперь запросы, URI которых начинаются на `/images/`,
будут обрабатываться в `/static/images`.
Другие запросы будут обрабатываться в `/static/www`.
Если файл не найден, отобразится ошибка `404`.
Например, на запрос `http://<имя_хоста>/images/image1.png`
будет отдан файл `/static/images/image1.png`,
а на запрос `http://<имя_хоста>/files/index.html`
будет отдан файл `/static/www/files/index.html`.
# https://angie.software/adc/docs/load_balancer/reference.md
# Справочная информация
Справочные материалы по настройке балансировщика Angie ADC.
## Общие сведения
В этих статьях рассказывается о различных аспектах обработки запросов и взаимодействия с другими серверами.
- [Конфигурационные файлы](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile)
- [Соединения, сессии, запросы, логи](https://angie.software//adc/docs/load_balancer/reference/processing.md#adc-processing)
- [Режим отладки](https://angie.software//adc/docs/load_balancer/reference/debug-logging.md#adc-debug-logging)
## Основной модуль
| [Основной модуль](https://angie.software//adc/docs/load_balancer/reference/core.md#adc-core) | Управление служебными файлами, процессами и другими модулями Angie ADC. |
|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
## HTTP-модули
| [HTTP-модули](https://angie.software//adc/docs/load_balancer/reference/http/index.md#adc-modules-http) | Обработка HTTP-запросов и ответов,
управление HTTP-сервером, соединениями и статическими файлами. |
|----------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
## Потоковые модули
| [Потоковые модули](https://angie.software//adc/docs/load_balancer/reference/stream/index.md#adc-modules-stream) | Обработка HTTP-запросов и ответов,
управление HTTP-сервером, соединениями и статическими файлами. |
|-------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
## Почтовые модули
| [Почтовые модули](https://angie.software//adc/docs/load_balancer/reference/mail/index.md#adc-modules-mail) | Функциональность почтового прокси-сервера. |
|--------------------------------------------------------------------------------------------------------------|----------------------------------------------|
## Сторонние модули
| [GeoIP2](https://angie.software//adc/docs/load_balancer/reference/external-modules/geoip2.md#adc-external-geoip2) | Добавляет поиск по геоданным в базах MaxMind GeoIP2. |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
| [NJS](https://angie.software//adc/docs/load_balancer/reference/external-modules/njs.md#adc-external-njs):
- [HTTP JS](https://angie.software//adc/docs/load_balancer/reference/external-modules/http_js.md#adc-http-js)
- [Stream JS](https://angie.software//adc/docs/load_balancer/reference/external-modules/stream_js.md#adc-stream-js) | Позволяют использовать njs, подмножество языка JavaScript, в конфигурации Angie ADC
соответственно в контекстах `http` и `stream`. |
## Инструкции
- [Настройка ACME](https://angie.software//adc/docs/load_balancer/reference/acme.md#adc-acme-config)
## Указатель директив
[Указатель директив](/adc/docs/directives/)
# https://angie.software/adc/docs/load_balancer/reference/configfile.md
# Конфигурационные файлы
Angie ADC использует текстовый конфигурационный файл. По умолчанию этот файл
называется `angie.conf` и обычно находится в директории `/etc/angie`.
Конфигурационный файл обычно состоит из следующих контекстов:
- [events](https://angie.software//adc/docs/load_balancer/reference/core.md#adc-events) — общая обработка соединений;
- [http](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-d-http) — HTTP-трафик;
- [stream](https://angie.software//adc/docs/load_balancer/reference/stream/stream.md#adc-s-stream) — TCP- и UDP-трафик.
Директивы, размещенные вне этих контекстов, считаются находящимися в
контексте `main`:
```nginx
user angie; # директива в контексте 'main'
events {
# конфигурация обработки соединений
}
http {
# Конфигурация трафика HTTP, для всех вложенных виртуальных серверов
server {
# конфигурация виртуального HTTP сервера 1
location /one {
# конфигурация обработки HTTP запросов с URI, начинающимися с '/one'
}
location /two {
# конфигурация обработки HTTP запросов с URI, начинающимися с '/two'
}
}
server {
# конфигурация виртуального HTTP сервера 2
}
}
stream {
# Конфигурация трафика TCP/UDP, для всех вложенных виртуальных серверов
server {
# конфигурация виртуального TCP сервера 1
}
}
```
Для упрощения управления конфигурацией рекомендуется использовать директиву
[include](https://angie.software//adc/docs/load_balancer/reference/core.md#adc-include) в основном файле `angie.conf`, чтобы ссылаться на содержимое
файлов, специфичных для функций:
```nginx
include /etc/angie/http.d/*.conf;
include /etc/angie/stream.d/*.conf;
```
## Наследование
В общем случае дочерний контекст (тот, который содержится в другом контексте,
который считается родительским) унаследует настройки директив, определенных на
уровне родителя. Некоторые директивы могут появляться в нескольких контекстах;
в таких случаях вы можете переопределить настройки, унаследованные от родителя,
включив директиву в дочерний контекст.
## Синтаксис
### Единицы измерения
Размеры можно указывать в следующих единицах:
| Без суффикса | Байты |
|----------------|-----------|
| `k`, `K` | Килобайты |
| `m`, `M` | Мегабайты |
| `g`, `G` | Гигабайты |
Например: `1024`, `8k`, `1m`, `16g`.
Интервалы времени можно указывать в миллисекундах, секундах, минутах, часах,
днях и так далее, с использованием следующих суффиксов:
| `ms` | Миллисекунды |
|--------|------------------------------------------|
| `s` | Секунды |
| `m` | Минуты |
| `h` | Часы |
| `d` | Дни |
| `w` | Недели |
| `M` | Месяцы (принято считать равными 30 дням) |
| `y` | Годы (принято считать равными 365 дням) |
Несколько единиц могут быть объединены в одном значении, указывая их в порядке
от наиболее значимого к наименее значимому, при необходимости разделяя
пробелами. Например, `"1h 30m"` обозначает тот же промежуток времени, что
и `"90m"` или `"5400s"`. Значение без суффикса интерпретируется как
секунды. Рекомендуется всегда указывать суффикс.
Некоторые интервалы времени могут быть указаны только с разрешением в секундах.
### Директивы
Каждая директива состоит из имени и набора параметров.
Если какая-либо часть директивы должна содержать пробелы,
она должна быть заключена в кавычки или экранирована:
```nginx
add_header X-MyHeader "foo bar";
add_header X-MyHeader foo\ bar;
```
Если именованный параметр требует пробелов и вы используете кавычки,
его имя также должно быть заключено в кавычки:
```nginx
server example.com "sid=server 1";
```
## Настройка хэшей
Для эффективной обработки статических наборов данных, таких как имена серверов,
значения директивы [map](https://angie.software//adc/docs/load_balancer/reference/http/http_map.md#adc-map), MIME-типы и имена заголовков запросов, Angie ADC
использует хэш-таблицы. При запуске и каждом переопределении конфигурации
Angie ADC определяет оптимальный размер для этих хэш-таблиц, чтобы размер
корзины, которая хранит ключи с одинаковыми хэш-значениями, не превышал заданный
параметр (hash bucket size). Размер таблицы измеряется в корзинах и
корректируется до тех пор, пока не превысит параметр hash max size.
Большинство хэш-таблиц имеют соответствующие директивы для настройки этих
параметров, такие как [server_names_hash_max_size](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-server-names-hash-max-size) и
[server_names_hash_bucket_size](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-server-names-hash-bucket-size) для имен серверов.
Параметр hash bucket size выравнивается по кратности размера линии кэша
процессора. Такое выравнивание улучшает эффективность поиска ключей на
современных процессорах, уменьшая количество обращений к памяти. Если hash
bucket size равен размеру одной линии кэша, максимальное количество обращений к
памяти во время поиска ключа будет два: одно для вычисления адреса корзины и
второе для поиска внутри корзины. Поэтому, если Angie ADC сообщает, что следует
увеличить либо hash max size, либо hash bucket size, начните с увеличения
hash max size.
### Перезагрузка конфигурации
Перезагрузка конфигурационного файла происходит автоматически при сохранении изменений
в конфигурации балансировщика нагрузки. Подробнее см. [Настройка конфигурации](https://angie.software//adc/docs/load_balancer/config.md#adc-load-balancer-config).
# https://angie.software/adc/docs/load_balancer/reference/processing.md
# Соединения, сессии, запросы, логи
## Механизмы обработки соединений
Angie поддерживает различные методы обработки соединений. Доступность
конкретного метода зависит от используемой платформы. На платформах,
поддерживающих несколько методов, Angie обычно автоматически выбирает
наиболее эффективный метод. Однако, при необходимости, метод обработки
соединений можно явно выбрать с помощью директивы [use](https://angie.software//adc/docs/load_balancer/reference/core.md#adc-use).
Доступны следующие методы обработки соединений:
| Метод | Описание |
|-------------|-----------------------------------------------------------------------------------------------------------------------------|
| `select` | Стандартный метод. Соответствующий модуль собирается автоматически на
платформах, не имеющих более эффективных методов. |
| `poll` | Стандартный метод. Соответствующий модуль собирается автоматически на
платформах, не имеющих более эффективных методов. |
| `kqueue` | Эффективный метод, доступный на FreeBSD 4.1+, OpenBSD 2.9+, NetBSD 2.0 и
macOS. |
| `epoll` | Эффективный метод, доступный на Linux 2.6+. |
| `/dev/poll` | Эффективный метод, доступный на Solaris 7 11/99+, HP/UX 11.22+
(eventport), IRIX 6.5.15+ и Tru64 UNIX 5.1A+. |
| `eventport` | Метод `event ports` доступен на Solaris 10+. (Из-за известных
проблем рекомендуется использовать метод `/dev/poll`.) |
## Обработка HTTP-запросов
Каждый HTTP-запрос проходит через ряд фаз, на каждой из которых выполняется
определенный тип обработки.
| `Post-read` | Начальная фаза. Модуль [RealIP](https://angie.software//adc/docs/load_balancer/reference/http/http_realip.md#adc-http-realip) вызывается на
этой фазе. |
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Server-rewrite` | Фаза, на которой обрабатываются директивы из модуля [Rewrite](https://angie.software//adc/docs/load_balancer/reference/http/http_rewrite.md#adc-http-rewrite), определенные в блоке `server` (но вне блока
`location`). |
| `Find-config` | Специальная фаза, на которой выбирается [location](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-location) на основе URI
запроса. |
| `Rewrite` | Похожа на фазу `Server-rewrite`, но применяется к правилам
[rewrite](https://angie.software//adc/docs/load_balancer/reference/http/http_rewrite.md#adc-rewrite), определенным в блоке location, выбранном на предыдущей
фазе. |
| `Post-rewrite` | Специальная фаза, на которой запрос перенаправляется в новое место, как
на фазе `Find-config`, если его URI был изменен во время фазы
`Rewrite`. |
| `Preaccess` | На этой фазе стандартные модули Angie, такие как [Limit Req](https://angie.software//adc/docs/load_balancer/reference/http/http_limit_req.md#adc-http-limit-req), регистрируют свои обработчики. |
| `Access` | Фаза, на которой проверяется право клиента на выполнение запроса, обычно
с помощью стандартных модулей Angie, таких как [Auth Basic](https://angie.software//adc/docs/load_balancer/reference/http/http_auth_basic.md#adc-http-auth-basic). |
| `Post-access` | Специальная фаза, на которой обрабатывается директива [satisfy any](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-satisfy). |
| `Precontent` | На этой фазе стандартные модули, такие как директивы [try_files](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-try-files) и
[mirror](https://angie.software//adc/docs/load_balancer/reference/http/http_mirror.md#adc-mirror), регистрируют свои обработчики. |
| `Content` | Фаза, на которой обычно генерируется ответ.
На этом этапе несколько стандартных модулей Angie
регистрируют свои обработчики,
включая [Index](https://angie.software//adc/docs/load_balancer/reference/http/http_index.md#adc-http-index);
также сюда относятся директивы [proxy_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-pass), [fastcgi_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_fastcgi.md#adc-fastcgi-pass),
[uwsgi_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_uwsgi.md#adc-uwsgi-pass), [scgi_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_scgi.md#adc-scgi-pass) и [grpc_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_grpc.md#adc-grpc-pass).
Обработчики вызываются последовательно,
пока один из них не произведет вывод. |
| `Log` | Финальная фаза, на которой выполняется логирование запросов. В настоящее
время только модуль [Log](https://angie.software//adc/docs/load_balancer/reference/http/http_log.md#adc-http-log) регистрирует свой
обработчик на этом этапе для ведения журнала доступа. |
## Обработка TCP/UDP-сессий
TCP/UDP-сессия от клиента проходит через ряд фаз, на каждой из которых
выполняется определенный тип обработки:
| `Post-accept` | Начальная фаза после принятия соединения от клиента. На этой фазе
вызывается модуль [RealIP](https://angie.software//adc/docs/load_balancer/reference/stream/stream_realip.md#adc-stream-realip). |
|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Pre-access` | Предварительная фаза для проверки доступа. Модули [Set](https://angie.software//adc/docs/load_balancer/reference/stream/stream_set.md#adc-stream-set) вызываются на этой фазе. |
| `Access` | Фаза для ограничения доступа клиента перед фактической обработкой данных.
На этом этапе вызывается модуль [Access](https://angie.software//adc/docs/load_balancer/reference/stream/stream_access.md#adc-stream-access). |
| `SSL` | Фаза, на которой происходит терминация TLS/SSL.
На этой фазе вызывается модуль [SSL](https://angie.software//adc/docs/load_balancer/reference/stream/stream_ssl.md#adc-stream-ssl). |
| `Preread` | Фаза для чтения начальных байт данных в [preread buffer](https://angie.software//adc/docs/load_balancer/reference/stream/stream.md#adc-s-preread-buffer-size), чтобы позволить таким модулям, как [SSL
Preread](https://angie.software//adc/docs/load_balancer/reference/stream/stream_ssl_preread.md#adc-stream-ssl-preread), проанализировать данные до их
обработки. |
| `Content` | Обязательная фаза, на которой данные фактически обрабатываются, обычно с
участием модуля [Return](https://angie.software//adc/docs/load_balancer/reference/stream/stream_return.md#adc-stream-return), который отправляет
ответ клиенту.
Директива [proxy_pass](https://angie.software//adc/docs/load_balancer/reference/stream/stream_proxy.md#adc-s-proxy-pass) также относится сюда. |
| `Log` | Финальная фаза, на которой фиксируется результат обработки сессии
клиента. На этой фазе вызывается модуль [Log](https://angie.software//adc/docs/load_balancer/reference/stream/stream_log.md#adc-stream-log). |
## Обработка запросов
### Выбор виртуального сервера
Изначально соединение создается в контексте сервера по умолчанию. Имя сервера
может быть определено на следующих этапах обработки запроса, каждый из которых
участвует в выборе конфигурации сервера:
- Во время SSL-рукопожатия, заранее, в соответствии с SNI.
- После обработки строки запроса.
- После обработки поля заголовка `Host`.
Если имя сервера не определено после обработки строки запроса или поля заголовка
`Host`, Angie использует пустое имя в качестве имени сервера.
На каждом из этих этапов могут применяться различные конфигурации сервера.
Поэтому некоторые директивы следует указывать с осторожностью:
- В случае директивы [ssl_protocols](https://angie.software//adc/docs/load_balancer/reference/http/http_ssl.md#adc-ssl-protocols) список протоколов устанавливается
библиотекой OpenSSL до применения конфигурации сервера в соответствии с
именем, запрошенным через SNI. В результате протоколы следует указывать только
для сервера по умолчанию.
- Директивы [client_header_buffer_size](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-client-header-buffer-size) и [merge_slashes](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-merge-slashes) применяются
до чтения строки запроса. Поэтому эти директивы используют либо конфигурацию
сервера по умолчанию, либо конфигурацию сервера, выбранную через SNI.
- В случае директив [ignore_invalid_headers](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-ignore-invalid-headers),
[large_client_header_buffers](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-large-client-header-buffers) и [underscores_in_headers](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-underscores-in-headers), которые
участвуют в обработке полей заголовков запроса, конфигурация сервера
дополнительно зависит от того, была ли она обновлена в соответствии со строкой
запроса или полем заголовка `Host`.
- Ответ с ошибкой обрабатывается с использованием директивы [error_page](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-error-page) на
сервере, который в данный момент обрабатывает запрос.
### Виртуальные серверы на основе имен
Сначала Angie ADC определяет, какой сервер должен обрабатывать запрос.
Рассмотрим простую конфигурацию, где все три виртуальных сервера слушают на
порту 80:
```nginx
server {
listen 80;
server_name example.org www.example.org;
# ...
}
server {
listen 80;
server_name example.net www.example.net;
# ...
}
server {
listen 80;
server_name example.com www.example.com;
# ...
}
```
В этой конфигурации Angie ADC определяет, какой сервер должен обработать запрос,
основываясь исключительно на поле заголовка `Host`. Если значение этого
заголовка не совпадает ни с одним из имен серверов или если запрос не содержит
этого заголовка, Angie ADC направит запрос к серверу по умолчанию для этого
порта. В приведенной выше конфигурации сервером по умолчанию является первый —
что является стандартным поведением Angie ADC. Также можно явно указать, какой
сервер должен быть сервером по умолчанию, используя параметр
`default_server` в директиве [listen](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-listen):
```nginx
server {
listen 80 default_server;
server_name example.net www.example.net;
# ...
}
```
#### NOTE
Обратите внимание, что сервер по умолчанию является свойством слушающего
сокета, а не имени сервера.
### Международные имена
Международные доменные имена ([IDNs](https://en.wikipedia.org/wiki/Internationalized_domain_name)) должны
указываться в директиве [server_name](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-server-name) с использованием представления ASCII
(Punycode):
```nginx
server {
listen 80;
server_name xn--e1afmkfd.xn--80akhbyknj4f; # пример.испытание
# ...
}
```
### Запрет запросов с неопределенными именами серверов
Если запросы без заголовка `Host` нежелательны, можно определить
сервер, который просто отклоняет такие запросы:
```nginx
server {
listen 80;
server_name "";
return 444;
}
```
В этой конфигурации имя сервера задано пустой строкой, что соответствует
запросам без заголовка `Host`. Затем возвращается специальный
нестандартный код 444, который закрывает соединение.
### Сочетание виртуальных серверов, основанных на именах и IP-адресах
Рассмотрим более сложную конфигурацию, где некоторые виртуальные серверы слушают
на разных адресах:
```nginx
server {
listen 192.168.1.1:80;
server_name example.org www.example.org;
# ...
}
server {
listen 192.168.1.1:80;
server_name example.net www.example.net;
# ...
}
server {
listen 192.168.1.2:80;
server_name example.com www.example.com;
# ...
}
```
В этой конфигурации Angie ADC сначала проверяет IP-адрес и порт запроса по
директивам [listen](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-listen) блоков [server](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-server). Затем он проверяет поле заголовка
`Host` запроса по записям [server_name](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-server-name) блоков [server](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-server), которые
совпали с IP-адресом и портом. Если имя сервера не найдено, запрос будет
обработан сервером по умолчанию. Например, запрос к `www.example.com`,
полученный на порту 192.168.1.1:80, будет обработан сервером по умолчанию для
этого порта — т.е. первым сервером — поскольку `www.example.com` не
определен для этого порта.
Как упоминалось ранее, сервер по умолчанию является свойством слушающего сокета,
и можно определить разные серверы по умолчанию для разных портов:
```nginx
server {
listen 192.168.1.1:80;
server_name example.org www.example.org;
# ...
}
server {
listen 192.168.1.1:80 default_server;
server_name example.net www.example.net;
# ...
}
server {
listen 192.168.1.2:80 default_server;
server_name example.com www.example.com;
# ...
}
```
### Выбор локаций
Рассмотрим простую конфигурацию PHP-сайта:
```nginx
server {
listen 80;
server_name example.org www.example.org;
root /data/www;
location / {
index index.html index.php;
}
location ~* \.(gif|jpg|png)$ {
expires 30d;
}
location ~ \.php$ {
fastcgi_pass localhost:9000;
fastcgi_param SCRIPT_FILENAME
$document_root$fastcgi_script_name;
include fastcgi_params;
}
}
```
Angie сначала ищет наиболее конкретный префикс `location`, заданный
буквальными строками, независимо от их порядка в списке. В приведенной выше
конфигурации единственный префикс локации — это `location /`, который
соответствует любому запросу и будет использоваться в качестве последнего
средства. Затем Angie проверяет локации, определенные с помощью регулярных
выражений, в порядке их появления в конфигурационном файле. Первое совпадающее
выражение завершает поиск, и Angie использует эту `location`. Если ни
одно регулярное выражение не совпадает с запросом, Angie использует наиболее
конкретную префиксную `location`, найденную ранее.
#### NOTE
Локации всех типов проверяют только URI часть строки запроса, исключая
аргументы. Это связано с тем, что аргументы в строке запроса могут быть
указаны разными способами, например:
- `/index.php?user=john&page=1`
- `/index.php?page=1&user=john`
Кроме того, строка запроса может содержать любое количество параметров:
- `/index.php?page=1&something+else&user=john`
Теперь давайте рассмотрим, как запросы будут обрабатываться в приведенной выше
конфигурации:
- Запрос `/logo.gif` сначала соответствует префиксу `location /`, а
затем регулярному выражению `.(gif|jpg|png)$`. Поэтому он
обрабатывается последней локацией. Используя директиву `root /data/www`,
запрос сопоставляется с файлом `/data/www/logo.gif`, и файл отправляется
клиенту.
- Запрос `/index.php` также изначально соответствует префиксу
`location /`, а затем регулярному выражению `.(php)$`.
Следовательно, он обрабатывается последней локацией, и запрос передается
серверу FastCGI, слушающему на `localhost:9000`. Директива
[fastcgi_param](https://angie.software//adc/docs/load_balancer/reference/http/http_fastcgi.md#adc-fastcgi-param) устанавливает параметр FastCGI `SCRIPT_FILENAME` в
`/data/www/index.php`, и сервер FastCGI выполняет файл. Переменная
[$document_root](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-v-document-root) устанавливается в значение директивы `root`, а
переменная [$fastcgi_script_name](https://angie.software//adc/docs/load_balancer/reference/http/http_fastcgi.md#adc-v-fastcgi-script-name) устанавливается в URI запроса, т.е.
`/index.php`.
- Запрос `/about.html` соответствует только префиксу `location /`,
поэтому он обрабатывается в этой локации. Используя директиву `root
/data/www`, запрос сопоставляется с файлом `/data/www/about.html`, и
файл отправляется клиенту.
Обработка запроса `/` более сложна. Он соответствует только префиксу
`location /`, поэтому он обрабатывается в этой локации. Директива
[index](https://angie.software//adc/docs/load_balancer/reference/http/http_index.md#adc-index) затем проверяет наличие индексных файлов в соответствии с ее
параметрами и директивой `root /data/www`. Если файл
`/data/www/index.html` не существует, но файл `/data/www/index.php`
существует, директива выполняет внутреннюю переадресацию на `/index.php`,
и Angie снова ищет локации, как если бы запрос был отправлен клиентом. Как
упоминалось ранее, переадресованный запрос в конечном итоге будет обработан
сервером FastCGI.
## Проксирование и балансировка нагрузки
Одним из распространенных способов использования Angie ADC является настройка в
качестве прокси-сервера. В этой роли Angie ADC принимает запросы, перенаправляет
их на проксируемые серверы, получает ответы от этих серверов и отправляет ответы
обратно клиентам.
Простой прокси-сервер:
```nginx
server {
location / {
proxy_pass http://backend:8080;
}
```
Директива [proxy_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-pass) заставит Angie ADC передавать запросы клиентов на
сервер `backend:8080` (прокси-сервер). Существует множество дополнительных
[директив](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-http-proxy), которые можно использовать для дальнейшей
настройки прокси-соединения.
### Проксирование FastCGI
Angie ADC может использоваться для маршрутизации запросов на FastCGI-серверы,
которые выполняют приложения, построенные с использованием различных фреймворков
и языков программирования, таких как PHP.
Простейшая конфигурация Angie ADC для работы с FastCGI-сервером включает
использование директивы [fastcgi_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_fastcgi.md#adc-fastcgi-pass) вместо директивы [proxy_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-pass),
а также директив [fastcgi_param](https://angie.software//adc/docs/load_balancer/reference/http/http_fastcgi.md#adc-fastcgi-param) для установки параметров, передаваемых
FastCGI-серверу. Предположим, что FastCGI-сервер доступен по адресу
`localhost:9000`. В PHP параметр `SCRIPT_FILENAME` используется для
определения имени скрипта, а параметр `QUERY_STRING` используется для
передачи параметров запроса. Результирующая конфигурация будет следующей:
```nginx
server {
location / {
fastcgi_pass localhost:9000;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param QUERY_STRING $query_string;
}
location ~ \.(gif|jpg|png)$ {
root /data/images;
}
}
```
Эта конфигурация настраивает сервер, который направляет все запросы, кроме
запросов к статическим изображениям, на проксируемый сервер, работающий на
`localhost:9000` через протокол FastCGI.
### Проксирование WebSocket
Для обновления соединения с HTTP/1.1 до WebSocket используется механизм
[протокольного переключения](https://datatracker.ietf.org/doc/html/rfc2616#section-14.42), доступный в
HTTP/1.1.
Однако есть тонкость: поскольку заголовок `Upgrade` является [заголовком
перехода](https://datatracker.ietf.org/doc/html/rfc2616#section-13.5.1), он не
передается от клиента к проксируемому серверу. При использовании прямого
проксирования клиенты могут использовать метод CONNECT для обхода этой проблемы.
Этот подход не работает при обратном проксировании, так как клиенты не
осведомлены о каких-либо прокси-серверах, и требуется специальная обработка на
прокси-сервере.
Angie ADC реализует специальный режим работы, который позволяет установить
туннель между клиентом и проксируемым сервером, если проксируемый сервер
возвращает ответ с кодом 101 (Switching Protocols), а клиент запрашивает
переключение протокола через заголовок `Upgrade` в запросе.
Как уже упоминалось, заголовки перехода, включая `Upgrade` и
`Connection`, не передаются от клиента к проксируемому серверу. Поэтому,
чтобы проксируемый сервер был осведомлен о намерении клиента переключиться на
протокол WebSocket, эти заголовки должны быть переданы явно:
```nginx
location /chat/ {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
```
Более сложный пример демонстрирует, как значение поля заголовка
`Connection` в запросе к проксируемому серверу зависит от наличия поля
`Upgrade` в заголовке запроса клиента:
```nginx
http {
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
...
location /chat/ {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
}
}
```
По умолчанию соединение будет закрыто, если проксируемый сервер не передает
никаких данных в течение 60 секунд. Этот тайм-аут можно увеличить с помощью
директивы [proxy_read_timeout](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-read-timeout). В качестве альтернативы: на проксируемом
сервере можно настроить периодическую отправку кадров WebSocket ping для
сброса тайм-аута и проверки того, активно ли соединение.
### Балансировка нагрузки
Балансировка нагрузки между несколькими экземплярами приложения — это широко
используемая техника для оптимизации использования ресурсов, максимизации
пропускной способности, уменьшения задержек и обеспечения отказоустойчивых
конфигураций.
Angie ADC можно использовать в качестве высокоэффективного HTTP-балансировщика
нагрузки для распределения трафика между несколькими серверами приложений, тем
самым улучшая производительность, масштабируемость и надежность веб-приложений.
Самая простая конфигурация для балансировки нагрузки с помощью Angie ADC может
выглядеть следующим образом:
```nginx
http {
upstream myapp1 {
server srv1.example.com;
server srv2.example.com;
server srv3.example.com;
}
server {
listen 80;
location / {
proxy_pass http://myapp1;
}
}
}
```
В приведенном примере три экземпляра одного и того же приложения работают на
серверах с `srv1` по `srv3`. Когда метод балансировки нагрузки не
настроен явно, по умолчанию используется круговой метод (round-robin).
Реализация обратного прокси
в Angie также поддерживает встроенные (или пассивные) проверки состояния
серверов. Эти проверки настраиваются с помощью директив [max_fails](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-max-fails) и [fail_timeout](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-fail-timeout) внутри блока [server](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-u-server) в контексте [upstream](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-u-upstream).
## Логирование
### Syslog
Директивы [error_log](https://angie.software//adc/docs/load_balancer/reference/core.md#adc-error-log) и [access_log](https://angie.software//adc/docs/load_balancer/reference/http/http_log.md#adc-access-log) поддерживают логирование в
`syslog`. Для настройки логирования в `syslog` используются
следующие параметры:
| `server=`address | Указывает адрес сервера `syslog`. Адрес может быть доменным именем
или IP-адресом с необязательным портом, либо путем к UNIX-доменному
сокету, указанным после префикса `"unix:"`. Если порт не указан,
используется UDP-порт 514. Если доменное имя разрешается в несколько
IP-адресов, используется первый разрешенный адрес. |
|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `facility=`string | Устанавливает уровень для сообщений `syslog`, как определено в [RFC
3164](https://datatracker.ietf.org/doc/html/rfc3164.html). Возможные
уровни включают: `"kern"`, `"user"`, `"mail"`,
`"daemon"`, `"auth"`, `"intern"`, `"lpr"`,
`"news"`, `"uucp"`, `"clock"`, `"authpriv"`,
`"ftp"`, `"ntp"`, `"audit"`, `"alert"`,
`"cron"`, `"local0".."local7"`. По умолчанию используется
`"local7"`. |
| `severity=`string | Определяет уровень серьезности сообщений `syslog` для
[access_log](https://angie.software//adc/docs/load_balancer/reference/http/http_log.md#adc-access-log), как указано в [RFC 3164](https://datatracker.ietf.org/doc/html/rfc3164.html). Возможные
значения те же, что и для второго параметра (уровень) директивы
[error_log](https://angie.software//adc/docs/load_balancer/reference/core.md#adc-error-log). По умолчанию используется `"info"`. Серьезность
сообщений об ошибках определяется Angie, поэтому этот параметр
игнорируется в директиве [error_log](https://angie.software//adc/docs/load_balancer/reference/core.md#adc-error-log). |
| `tag=`string | Устанавливает тег для сообщений `syslog`. По умолчанию используется
тег `"angie"`. |
| `nohostname` | Отключает добавление поля `hostname` в заголовок сообщения
`syslog`. |
Пример конфигурации `syslog`:
```nginx
error_log syslog:server=192.168.1.1 debug;
access_log syslog:server=[2001:db8::1]:12345,facility=local7,tag=angie,severity=info combined;
```
# https://angie.software/adc/docs/load_balancer/reference/core.md
# Основной модуль
Модуль предоставляет основную функциональность и директивы конфигурации,
необходимые для базовой работы сервера, а также решает важные задачи,
такие как управление рабочими процессами,
настройка событийно-ориентированных моделей
и обработка входящих соединений и запросов.
Он включает ключевые директивы для настройки основного процесса,
ведения журналов ошибок и контроля поведения сервера на низком уровне.
## Пример конфигурации
```nginx
user www www;
worker_processes 2;
error_log /var/log/error.log info;
events {
use kqueue; worker_connections 2048;
}
```
## Директивы
### accept_mutex
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `accept_mutex` `on` | `off`; |
|------------------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `accept_mutex off;` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | events |
Когда `accept_mutex` включен,
рабочие процессы будут принимать новые соединения поочередно.
Иначе уведомления о новых соединениях получают все рабочие процессы,
что может привести к неэффективному использованию системных ресурсов,
если количество новых соединений невелико.
#### NOTE
Нет необходимости включать `accept_mutex` на системах,
которые поддерживают флаг `EPOLLEXCLUSIVE`,
или при использовании директивы [reuseport](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-listen).
### accept_mutex_delay
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `accept_mutex_delay` время; |
|------------------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `accept_mutex_delay 500ms;` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | events |
Если [accept_mutex](#adc-accept-mutex) включен,
эта директива указывает максимальное время,
в течение которого рабочий процесс ждет,
чтобы продолжить принимать новые соединения,
если другой рабочий процесс уже обрабатывает новые соединения.
### daemon
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `daemon` `on` | `off`; |
|------------------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию | `daemon on;` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Определяет, будет ли Angie запускаться в режиме демона.
Используется в основном для разработки.
### debug_connection
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `debug_connection` адрес | CIDR | `unix`:; |
|------------------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | events |
Включает отладочный лог для отдельных клиентских соединений.
Для остальных соединений используется уровень лога,
заданный директивой [error_log](#adc-error-log).
Указывать соединения можно по IPv4- или IPv6-адресу, сети или имени хоста.
Используйте параметр `unix:`, чтобы включить отладочный лог
для соединений через UNIX-сокеты.
```nginx
events {
debug_connection 127.0.0.1;
debug_connection localhost;
debug_connection 192.0.2.0/24;
debug_connection ::1;
debug_connection 2001:0db8::/32;
debug_connection unix:;
# ...
}
```
#### NOTE
Чтобы эта директива работала,
в сборке Angie должен быть включен отладочный лог.
### debug_points
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `debug_points` `abort` | `stop`; |
|------------------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Эта директива используется для отладки.
В случае обнаружения внутренней ошибки,
например, утечки сокетов в момент перезапуска рабочих процессов,
включение `debug_points` либо создаст файл дампа памяти (`abort`),
либо остановит процесс (`stop`) для анализа с помощью отладчика.
### env
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `env` переменная [=значение]; |
|------------------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `env TZ;` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
По умолчанию Angie удаляет все переменные окружения,
унаследованные от родительского процесса,
кроме переменной `TZ`.
Эта директива позволяет сохранить часть унаследованных переменных,
поменять их значения или создать новые переменные окружения.
Эти переменные затем доступны рабочими процессами.
Обратите внимание, что управление системными библиотеками таким образом
может быть не всегда эффективным, поскольку библиотеки часто проверяют переменные
только во время инициализации, которая происходит до срабатывания этой директивы.
Пример:
```nginx
env MALLOC_OPTIONS;
env PERL5LIB=/data/site/modules;
env OPENSSL_ALLOW_PROXY_CERTS=1;
```
#### NOTE
Переменная окружения `ANGIE` используется внутри Angie
и не должна задаваться напрямую пользователем.
### error_log
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `error_log` файл [уровень] [[`filter=`тип:значение] ...] [[`escape=``default` | `json`]]; |
|------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| По умолчанию | `error_log logs/error.log error;` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main, http, mail, stream, server, location |
Настраивает логирование,
позволяя указывать несколько логов на одном уровне конфигурации.
Если файл лога не указан явно на уровне конфигурации `main`,
будет использоваться файл по умолчанию.
Первый параметр указывает файл для хранения лога.
Специальное значение `stderr` задает стандартный поток ошибок.
Для настройки логирования в [syslog](https://angie.software//adc/docs/load_balancer/reference/processing.md#adc-syslog-logging)
используйте префикс `"syslog:"`.
Для логирования в циклический буфер памяти
используйте префикс `"memory:"`, за которым следует размер буфера;
обычно он используется для отладки.
Второй параметр задает уровень логирования одним из следующих значений:
`debug`, `info`, `notice`, `warn`, `error`,
`crit`, `alert` или `emerg`.
Уровни перечислены в порядке возрастания серьезности.
При задании уровня будут логироваться сообщения равного и более высокого уровня:
| Настройка | Уровни записи |
|-------------|--------------------------------------------------------------------------|
| `debug` | `debug`, `info`, `notice`, `warn`, `error`,
`crit`, `alert`, `emerg` |
| `info` | `info`, `notice`, `warn`, `error`,
`crit`, `alert`, `emerg` |
| `notice` | `notice`, `warn`, `error`,
`crit`, `alert`, `emerg` |
| `warn` | `warn`, `error`, `crit`, `alert`, `emerg` |
| `error` | `error`, `crit`, `alert`, `emerg` |
| `crit` | `crit`, `alert`, `emerg` |
| `alert` | `alert`, `emerg` |
| `emerg` | `emerg` |
Если этот параметр не задан,
по умолчанию используется уровень логирования `error`.
Необязательные параметры `filter=` ограничивают набор записываемых сообщений.
Поддерживаются следующие фильтры:
- `filter=file:`префикс — совпадение по префиксу имени файла
(например, `ngx_http_access_module.c`);
- `filter=event:`префикс — совпадение по префиксу идентификатора события
(например, `http.upstream.peer`);
- `filter=tag:`тег — совпадение по тегу записи.
Для `filter=file:` и `filter=event:` используется сравнение по префиксу;
достаточно любого совпадения. Для `filter=tag:` должны совпасть все заданные теги.
Теги добавляются модулями автоматически (например,
`http`, `stream`, `mail`, `upstream`,
`peer`, `subrequest`) и директивой
[error_log_user_tag](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-error-log-user-tag).
Параметр `escape=` задает режим экранирования вывода лога.
Значение по умолчанию `default` оставляет обычный текстовый формат.
Значение `json` форматирует каждую запись в логе как JSON‑объект.
#### NOTE
Чтобы работал уровень логирования `debug`,
должен быть включен [режим отладки](https://angie.software//angie/docs/troubleshooting.md#debug-logging).
Каждая запись в журнале ошибок имеет следующий формат:
```text
временная_метка [уровень] PID#TID: *id_запроса сообщение
```
Где:
- `временная_метка` — дата и время события;
- `уровень` — уровень логирования события;
- `PID#TID` — идентификаторы процесса и потока;
- `*id_запроса` — уникальный идентификатор запроса (если применимо);
- `сообщение` — текст сообщения об ошибке или событии.
### events
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `events` { ... }; |
|------------------------------------------------------------------------------------------------------|---------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Предоставляет контекст конфигурационного файла для директив,
влияющих на обработку соединений.
### include
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `include` файл | маска; |
|------------------------------------------------------------------------------------------------------|---------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | любой |
Включает в конфигурацию другой файл или файлы,
подходящие под заданную маску.
Включаемые файлы должны содержать синтаксически верные директивы и блоки.
Пример:
```nginx
include mime.types;
include vhosts/*.conf;
```
### lock_file
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `lock_file` файл; |
|------------------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `lock_file logs/angie.lock;` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Angie использует механизм блокировок для реализации [accept_mutex](#adc-accept-mutex)
и сериализации доступа к разделяемой памяти.
На большинстве систем блокировки управляются с помощью атомарных операций,
что делает эту директиву ненужной.
Однако на некоторых системах используется альтернативный механизм lock file.
Эта директива устанавливает префикс для имен файлов блокировок.
### master_process
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `master_process` `on` | `off`; |
|------------------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `master_process on;` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Определяет, будут ли запускаться рабочие процессы.
Эта директива предназначена для разработчиков Angie.
### multi_accept
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `multi_accept` `on` | `off`; |
|------------------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `multi_accept off;` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | events |
| `on` | Рабочий процесс будет принимать сразу все новые соединения. |
|--------|----------------------------------------------------------------------|
| `off` | Рабочий процесс будет принимать только одно новое соединение за раз. |
#### NOTE
Директива игнорируется
при использовании метода обработки соединений [kqueue](https://angie.software//adc/docs/load_balancer/reference/processing.md#adc-kqueue),
так как он сам задает число новых соединений, ожидающих приема.
### pcre_jit
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `pcre_jit` `on` | `off`; |
|------------------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `pcre_jit off;` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Разрешает или запрещает использование JIT-компиляции (PCRE JIT)
для регулярных выражений, известных на момент парсинга конфигурации.
Использование PCRE JIT заметно ускоряет обработку регулярных выражений.
#### NOTE
Для работы JIT необходима библиотека PCRE версии 8.20 или выше,
собранная с параметром сборки `--enable-jit`.
Если Angie собирается с библиотекой PCRE (`--with-pcre=`),
поддержка JIT включается с помощью параметра `--with-pcre-jit`.
### pid
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `pid` файл | `off`; |
|------------------------------------------------------------------------------------------------------|-----------------------|
| По умолчанию | `pid logs/angie.pid;` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Указывает файл, где будет храниться идентификатор главного процесса Angie.
Файл создается атомарно, что обеспечивает корректность его содержимого.
Настройка `off` отключает создание этого файла.
#### NOTE
Если значение file изменяется при переконфигурации,
но указывает на симлинк предыдущего PID-файла,
файл не будет создан заново.
### ssl_engine
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `ssl_engine` устройство; |
|------------------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Задает название аппаратного SSL-акселератора.
### ssl_object_cache_inheritable
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `ssl_object_cache_inheritable` `on` | `off`; |
|------------------------------------------------------------------------------------------------------|------------------------------------------------|
| Значение по умолчанию | `ssl_object_cache_inheritable on;` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Если включено, SSL-объекты (SSL-сертификаты, секретные ключи, доверенные
сертификаты CA, списки отзыва сертификатов) наследуются при перезагрузке
конфигурации.
SSL-объекты, загруженные из файлов, наследуются, если время их изменения и
индекс файла не изменились с момента предыдущей загрузки конфигурации. Секретные
ключи, указанные как `engine:name:id`, никогда не наследуются, тогда как
ключи, указанные как `data:value`, всегда наследуются.
SSL-объекты, загруженные из переменных, не могут быть унаследованы.
Пример:
```nginx
ssl_object_cache_inheritable on;
http {
server {
ssl_certificate example.com.crt;
ssl_certificate_key example.com.key;
}
}
```
### thread_pool
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `thread_pool` имя `threads=`число [`max_queue=`число]; |
|------------------------------------------------------------------------------------------------------|----------------------------------------------------------|
| По умолчанию | `thread_pool default threads=32 max_queue=65536;` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Задает имя и параметры пула потоков,
используемого для многопоточной обработки операций чтения и отправки файлов
[без блокирования](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-aio) рабочих процессов.
Параметр `threads` задает число потоков в пуле.
Если все потоки в пуле заняты выполнением заданий, новые задания ждут в очереди.
Параметр `max_queue` ограничивает число заданий,
ожидающих своего выполнения в очереди.
По умолчанию в очереди может находиться до 65536 заданий.
Если очередь переполнена, новые задания завершаются с ошибкой.
### timer_resolution
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `timer_resolution` интервал; |
|------------------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Уменьшает разрешение таймеров времени в рабочих процессах,
за счет чего уменьшается число системных вызовов `gettimeofday()`.
По умолчанию `gettimeofday()` вызывается при каждом получении событий из ядра.
При уменьшении разрешения функция вызывается только раз за указанный интервал.
Пример:
```nginx
timer_resolution 100ms;
```
Внутренняя реализация интервала зависит от используемого метода:
- Фильтр `EVFILT_TIMER`, если используется [kqueue](https://angie.software//adc/docs/load_balancer/reference/processing.md#adc-kqueue).
- Функция `timer_create()`, если используется [eventport](https://angie.software//adc/docs/load_balancer/reference/processing.md#adc-eventport).
- Функция `setitimer()`, в противном случае.
### use
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `use` метод; |
|------------------------------------------------------------------------------------------------------|----------------|
| По умолчанию | — |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | events |
Задает метод, используемый для [обработки соединений](https://angie.software//adc/docs/load_balancer/reference/processing.md#adc-methods-use).
Обычно нет необходимости задавать его явно,
поскольку по умолчанию Angie выбирает наиболее эффективный метод.
### user
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `user` пользователь [группа]; |
|------------------------------------------------------------------------------------------------------|------------------------------------------------------------|
| По умолчанию | `user <параметр сборки --user> <параметр сборки --group>;` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Задает пользователя и группу для рабочих процессов
Если задан только пользователь,
для группы также задается указанное имя пользователя.
### worker_aio_requests
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `worker_aio_requests` число; |
|------------------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `worker_aio_requests 32;` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | events |
При использовании [aio](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-aio) с методом обработки соединений [epoll](https://angie.software//adc/docs/load_balancer/reference/processing.md#adc-epoll)
задает максимум операций асинхронного ввода-вывода, ожидающих обработки,
для одного рабочего процесса.
### worker_connections
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `worker_connections` число; |
|------------------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `worker_connections 512;` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | events |
Задает максимум соединений, которые одновременно может открыть рабочий процесс.
Обратите внимание, что это число включает все соединения,
такие как соединения с проксируемыми серверами, а не только клиентские.
Кроме того, фактическое количество одновременных соединений
не может превышать системный лимит на открытые файлы,
который можно настроить с помощью [worker_rlimit_nofile](#adc-worker-rlimit-nofile).
### worker_cpu_affinity
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `worker_cpu_affinity` маска_CPU ...;
`worker_cpu_affinity` auto [маска_CPU]; |
|------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Привязывает рабочие процессы к группам процессоров.
Каждая группа процессоров задается битовой маской разрешенных процессоров.
Для каждого рабочего процесса должна быть задана отдельная группа.
По умолчанию рабочие процессы не привязаны к конкретным процессорам.
Пример:
```nginx
worker_processes 4;
worker_cpu_affinity 0001 0010 0100 1000;
```
Эта конфигурация привязывает каждый рабочий процесс к отдельному процессору.
В качестве альтернативы:
```nginx
worker_processes 2;
worker_cpu_affinity 0101 1010;
```
Это привязывает первый рабочий процесс к CPU0 и CPU2,
а второй рабочий процесс к CPU1 и CPU3.
Такая настройка подходит для гипертрединга.
Специальное значение `auto`
позволяет автоматически привязывать рабочие процессы к доступным процессорам:
```nginx
worker_processes auto;
worker_cpu_affinity auto;
```
С помощью необязательной маски можно ограничить процессоры,
доступные для автоматической привязки:
```nginx
worker_cpu_affinity auto 01010101;
```
#### NOTE
Директива доступна только на FreeBSD и Linux.
### worker_priority
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `worker_priority` число; |
|------------------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `worker_priority 0;` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Задает приоритет планирования рабочих процессов подобно тому,
как это делается командой **nice**:
отрицательное число означает более высокий приоритет.
Диапазон возможных значений — от -20 до 20.
Пример:
```nginx
worker_priority -10;
```
### worker_processes
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `worker_processes` число | `auto`; |
|------------------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `worker_processes 1;` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Задает число рабочих процессов.
Оптимальное значение зависит от разных факторов, включая число ядер процессора,
количество жестких дисков и характер нагрузки.
Если вы не уверены, рекомендуется начать с числа доступных ядер процессора.
Значение `auto` пытается автоматически определить оптимальное количество.
### worker_rlimit_core
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `worker_rlimit_core` размер; |
|------------------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Меняет ограничение на наибольший размер дампа памяти (`RLIMIT_CORE`)
для рабочих процессов.
Используется для увеличения ограничения без перезапуска главного процесса.
### worker_rlimit_nofile
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `worker_rlimit_nofile` число; |
|------------------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Меняет ограничение на максимальное число открытых файлов (`RLIMIT_NOFILE`)
для рабочих процессов.
Используется для увеличения ограничения без перезапуска главного процесса.
### worker_shutdown_timeout
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `worker_shutdown_timeout` время; |
|------------------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Задает таймаут в секундах для постепенного завершения рабочих процессов.
По истечении указанного времени
Angie попытается закрыть все открытые сейчас соединения,
чтобы ускорить завершение работы.
Постепенное завершение работы инициируется отправкой сигнала QUIT
главному процессу, который приказывает рабочим процессам
прекратить принимать новые подключения, позволяя завершить уже существующие.
Рабочие процессы продолжают обрабатывать активные запросы до их завершения,
после чего корректно завершают свою работу. Если соединения остаются открытыми
дольше `worker_shutdown_timeout`, Angie принудительно закроет эти
соединения для завершения работы.
Также клиентские постоянные соединения закрываются только в случае,
если они неактивны не менее времени, заданного в [lingering_timeout](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-lingering-timeout).
### working_directory
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `working_directory` каталог; |
|------------------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | main |
Задает каталог, который будет текущим для рабочего процесса.
Основное применение — запись дампа памяти,
поэтому рабочий процесс должен иметь права на запись в этот каталог.
# https://angie.software/adc/docs/load_balancer/reference/http.md
# HTTP-модули
| [HTTP](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-http-core) | Основная функциональность для обработки HTTP-запросов и ответов,
управления HTTP-сервером, соединениями и статическими файлами. |
|---------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Access](https://angie.software//adc/docs/load_balancer/reference/http/http_access.md#adc-http-access) | Контроль доступа на основе IP-адресов и диапазонов CIDR. |
| [ACME](https://angie.software//adc/docs/load_balancer/reference/http/http_acme.md#adc-http-acme) | Автоматическое получение и обновление SSL-сертификатов
по протоколу ACME для HTTP-серверов. |
| [Addition](https://angie.software//adc/docs/load_balancer/reference/http/http_addition.md#adc-http-addition) | Вставка заданного фрагмента до или после тела ответа. |
| [API](https://angie.software//adc/docs/load_balancer/reference/http/http_api.md#adc-http-api) | RESTful HTTP-интерфейс для получения базовой информации о веб-сервере и
его статистики в формате JSON,
а также управления группами проксируемых серверов. |
| [Auth Basic](https://angie.software//adc/docs/load_balancer/reference/http/http_auth_basic.md#adc-http-auth-basic) | Базовая HTTP-аутентификация для контроля доступа
по имени пользователя и паролю. |
| [Auth Request](https://angie.software//adc/docs/load_balancer/reference/http/http_auth_request.md#adc-http-auth-request) | Авторизация с помощью подзапроса к внешнему HTTP-сервису. |
| [AutoIndex](https://angie.software//adc/docs/load_balancer/reference/http/http_autoindex.md#adc-http-autoindex) | Автоматический листинг директорий без индексного файла. |
| [Browser](https://angie.software//adc/docs/load_balancer/reference/http/http_browser.md#adc-http-browser) (устарел) | Определение браузера на основе заголовка `User-Agent`. |
| [Charset](https://angie.software//adc/docs/load_balancer/reference/http/http_charset.md#adc-http-charset) | Настройка и преобразование кодировки ответа. |
| [DAV](https://angie.software//adc/docs/load_balancer/reference/http/http_dav.md#adc-http-dav) | Управление файлами на сервере по протоколу WebDAV. |
| [Empty GIF](https://angie.software//adc/docs/load_balancer/reference/http/http_empty_gif.md#adc-http-empty-gif) | Отдача однопиксельного прозрачного GIF. |
| [FastCGI](https://angie.software//adc/docs/load_balancer/reference/http/http_fastcgi.md#adc-http-fastcgi) | Проксирование запроса к FastCGI-серверу. |
| [FLV](https://angie.software//adc/docs/load_balancer/reference/http/http_flv.md#adc-http-flv) | Псевдо-стриминг файлов в формате Flash Video (FLV). |
| [Geo](https://angie.software//adc/docs/load_balancer/reference/http/http_geo.md#adc-http-geo) | Преобразование IP-адресов в заданные значения переменных. |
| [gRPC](https://angie.software//adc/docs/load_balancer/reference/http/http_grpc.md#adc-http-grpc) | Проксирование запроса к gRPC-серверу. |
| [GunZIP](https://angie.software//adc/docs/load_balancer/reference/http/http_gunzip.md#adc-http-gunzip) | Распаковка сжатых GZip-ответов для их модификации и в случаях,
когда клиент не поддерживает компрессию. |
| [GZip](https://angie.software//adc/docs/load_balancer/reference/http/http_gzip.md#adc-http-gzip) | Сжатие ответов методом GZip для экономии трафика. |
| [GZip Static](https://angie.software//adc/docs/load_balancer/reference/http/http_gzip_static.md#adc-http-gzip-static) | Отдача статических файлов, предварительно сжатых методом GZip. |
| [Headers](https://angie.software//adc/docs/load_balancer/reference/http/http_headers.md#adc-http-headers) | Изменение полей заголовка ответа. |
| [HTTP2](https://angie.software//adc/docs/load_balancer/reference/http/http_v2.md#adc-http-v2) | Обработка запросов по протоколу HTTP/2. |
| [HTTP3](https://angie.software//adc/docs/load_balancer/reference/http/http_v3.md#adc-http-v3) | Обработка запросов по протоколу HTTP/3. |
| [Index](https://angie.software//adc/docs/load_balancer/reference/http/http_index.md#adc-http-index) | Настройка индексных файлов,
обслуживающих запросы с косой чертой в конце (`/`). |
| [Limit Conn](https://angie.software//adc/docs/load_balancer/reference/http/http_limit_conn.md#adc-http-limit-conn) | Ограничение числа одновременных запросов (активных соединений)
для защиты от перегрузки. |
| [Limit Req](https://angie.software//adc/docs/load_balancer/reference/http/http_limit_req.md#adc-http-limit-req) | Ограничение частоты запросов
для защиты от перегрузки и подбора паролей. |
| [Log](https://angie.software//adc/docs/load_balancer/reference/http/http_log.md#adc-http-log) | Настройка журнала запросов для отслеживания обращений к ресурсам
с целью мониторинга и анализа. |
| [Map](https://angie.software//adc/docs/load_balancer/reference/http/http_map.md#adc-http-map) | Преобразование переменных на основе предопределенных пар "ключ-значение". |
| [Memcached](https://angie.software//adc/docs/load_balancer/reference/http/http_memcached.md#adc-http-memcached) | Получение ответов от Memcached-сервера. |
| [Metric](https://angie.software//adc/docs/load_balancer/reference/http/http_metric.md#adc-http-metric) | Пользовательские числовые метрики в API статистики. |
| [Mirror](https://angie.software//adc/docs/load_balancer/reference/http/http_mirror.md#adc-http-mirror) | Зеркалирование запросов на другие серверы. |
| [MP4](https://angie.software//adc/docs/load_balancer/reference/http/http_mp4.md#adc-http-mp4) | Псевдо-стриминг файлов в формате MP4. |
| [Prometheus](https://angie.software//adc/docs/load_balancer/reference/http/http_prometheus.md#adc-http-prometheus) | Метрики сервера в формате, совместимом с Prometheus,
для мониторинга и сбора статистики. |
| [Proxy](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-http-proxy) | Реверсивное проксирование запросов к другим HTTP-серверам. |
| [Random Index](https://angie.software//adc/docs/load_balancer/reference/http/http_random_index.md#adc-http-random-index) | Случайный выбор индексного файла для запросов,
оканчивающихся косой чертой (`/`). |
| [RealIP](https://angie.software//adc/docs/load_balancer/reference/http/http_realip.md#adc-http-realip) | Определение адреса и порта клиента
при работе за другим прокси-сервером. |
| [Referer](https://angie.software//adc/docs/load_balancer/reference/http/http_referer.md#adc-http-referer) | Валидация значений заголовка `Referer`. |
| [Rewrite](https://angie.software//adc/docs/load_balancer/reference/http/http_rewrite.md#adc-http-rewrite) | Модификация URI запроса, перенаправления, установка переменных
и выбор конфигурации по условию. |
| [SCGI](https://angie.software//adc/docs/load_balancer/reference/http/http_scgi.md#adc-http-scgi) | Проксирование запроса к SCGI-серверу. |
| [Secure Link](https://angie.software//adc/docs/load_balancer/reference/http/http_secure_link.md#adc-http-secure-link) | Создание защищенных ссылок с возможностью ограничения срока доступа. |
| [Slice](https://angie.software//adc/docs/load_balancer/reference/http/http_slice.md#adc-http-slice) | Разделение запроса на множество подзапросов к отдельным фрагментам
для лучшего кэширования больших ответов. |
| [Split Clients](https://angie.software//adc/docs/load_balancer/reference/http/http_split_clients.md#adc-http-split-clients) | Создание переменных для A/B-тестирования, канареечных релизов, шардинга
и других сценариев, требующих разделения по пропорциональным группам. |
| [SSI](https://angie.software//adc/docs/load_balancer/reference/http/http_ssi.md#adc-http-ssi) | Обработка команд SSI (Server Side Includes) в ответах. |
| [SSL](https://angie.software//adc/docs/load_balancer/reference/http/http_ssl.md#adc-http-ssl) | Настройка SSL/TLS для обработки запросов по протоколу HTTPS. |
| [Stub Status](https://angie.software//adc/docs/load_balancer/reference/http/http_stub_status.md#adc-http-stub-status) (устарел) | Глобальные счетчики соединений и запросов в текстовом формате. |
| [Sub](https://angie.software//adc/docs/load_balancer/reference/http/http_sub.md#adc-http-sub) | Поиск и замена фрагментов в теле ответа. |
| [Upstream](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-http-upstream) | Настройка групп проксируемых серверов для балансировки нагрузки. |
| [Upstream Probe](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream_probe.md#adc-http-upstream-probe) | Настройка активных проверок работоспособности
для групп проксируемых серверов. |
| [UserID](https://angie.software//adc/docs/load_balancer/reference/http/http_userid.md#adc-http-userid) | Выдача и обработка cookie с уникальным идентификатором клиента
для отслеживания сеансов и аналитики. |
| [uWSGI](https://angie.software//adc/docs/load_balancer/reference/http/http_uwsgi.md#adc-http-uwsgi) | Проксирование запроса к uWSGI-серверу. |
# https://angie.software/adc/docs/load_balancer/reference/http/http.md
# HTTP-модуль
Базовый HTTP-модуль реализует основную функциональность HTTP-сервера: это
определение серверных блоков, настройка локаций для маршрутизации запросов,
передача статических файлов и контроль доступа, настройка перенаправлений,
поддержка соединений keep-alive и управление заголовками запросов и ответов.
Остальные модули этого раздела расширяют эту функциональность, позволяя гибко
настраивать и оптимизировать работу HTTP-сервера под различные сценарии и
требования.
## Директивы
### absolute_redirect
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `absolute_redirect` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `absolute_redirect on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если запрещено, то перенаправления, выдаваемые Angie, будут относительными.
См. также директивы [server_name_in_redirect](#adc-server-name-in-redirect) и [port_in_redirect](#adc-port-in-redirect).
### aio
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `aio` `on` | `off` | `threads` [=пул]; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `aio off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает использование файлового асинхронного ввода-вывода (AIO) во FreeBSD и Linux:
```nginx
location /video/ {
aio on;
output_buffers 1 64k;
}
```
Во FreeBSD AIO можно использовать, начиная с FreeBSD 4.3. До FreeBSD 11.0 AIO можно либо собрать в ядре статически:
```nginx
options VFS_AIO
```
либо загрузить динамически через загружаемый модуль ядра:
```nginx
kldload aio
```
В Linux AIO можно использовать только начиная с версии ядра 2.6.22. Кроме того, необходимо также дополнительно включить [directio](#adc-directio), иначе чтение будет блокирующимся:
```nginx
location /video/ {
aio on;
directio 512;
output_buffers 1 128k;
}
```
В Linux [directio](#adc-directio) можно использовать только для чтения блоков, выравненных на границу 512 байт (или 4К для XFS). Невыравненный конец файла будет читаться блокированно. То же относится к запросам с указанием диапазона запрашиваемых байт (byte-range requests) и к запросам FLV не с начала файла: чтение невыравненных начала и конца ответа будет блокирующимся.
При одновременном включении AIO и [sendfile](#adc-sendfile) в Linux для файлов, размер которых больше либо равен указанному в директиве [directio](#adc-directio), будет использоваться AIO, а для файлов меньшего размера или при выключенном [directio](#adc-directio) — [sendfile](#adc-sendfile):
```nginx
location /video/ {
sendfile on;
aio on;
directio 8m;
}
```
Кроме того, читать и [отправлять](https://angie.software//angie/docs/configuration/modules/http/index.md#sendfile) файлы можно в многопоточном режиме, не блокируя при этом рабочий процесс:
```nginx
location /video/ {
sendfile on;
aio threads;
}
```
Операции чтения или отправки файлов будут обрабатываться потоками из указанного [пула](https://angie.software//angie/docs/configuration/modules/core.md#thread-pool). Если пул потоков не задан явно, используется пул с именем `default`. Имя пула может быть задано при помощи переменных:
```nginx
aio threads=pool$disk;
```
Использование `aio on` требует сборки с конфигурационным параметром
`--with-file-aio`. Для использования `aio threads` требуется сборка
с параметром `--with-threads`.
В настоящий момент многопоточность совместима только с методами [epoll](https://angie.software//angie/docs/configuration/processing.md#epoll), [kqueue](https://angie.software//angie/docs/configuration/processing.md#kqueue) и [eventport](https://angie.software//angie/docs/configuration/processing.md#eventport). Отправка файлов в многопоточном режиме поддерживается
только на Linux.
См. также директиву [sendfile](#adc-sendfile).
### aio_write
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `aio_write` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `aio_write off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
При включенном [aio](#adc-aio) разрешает его использование для записи файлов. В настоящий момент это работает только при использовании `aio threads` и ограничено записью временных файлов с данными, полученными от проксируемых серверов.
### alias
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `alias` путь; |
|------------------------------------------------------------------------------------------|-----------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Задает замену для указанного `location`'а. Например, при такой конфигурации:
```nginx
location /i/ {
alias /data/w3/images/;
}
```
на запрос `/i/top.gif` будет отдан файл /data/w3/images/top.gif.
В значении параметра путь можно использовать переменные, кроме [$document_root](https://angie.software//angie/docs/configuration/modules/http/index.md#v-document-root) и [$realpath_root](https://angie.software//angie/docs/configuration/modules/http/index.md#v-realpath-root).
Если `alias` используется внутри `location`'а, заданного регулярным выражением, то регулярное выражение должно содержать группы захвата, а сам `alias` — ссылки на эти группы, например:
```nginx
location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ {
alias /data/w3/images/$1;
}
```
Если `location` и последняя часть значения директивы совпадают:
```nginx
location /images/ {
alias /data/w3/images/;
}
```
то лучше воспользоваться директивой [root](#adc-root):
```nginx
location /images/ {
root /data/w3;
}
```
### auth_delay
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_delay` время; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | `auth_delay 0s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задерживает обработку неавторизованных запросов с кодом ответа 401 для предотвращения атак по времени в случае ограничения доступа по [паролю](https://angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic) или по [результату подзапроса](https://angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request).
### auto_redirect
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `auto_redirect` [`on` | `off` | `default`]; |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| По умолчанию | `auto_redirect default;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Контролирует поведение [перенаправления](https://angie.software//angie/docs/configuration/modules/http/index.md#location-redirect),
когда префикс `location` заканчивается косой чертой:
```nginx
location /prefix/ {
auto_redirect on;
}
```
Здесь запрос к `/prefix` будет перенаправлен на `/prefix/`.
Значение `on` включает перенаправление в явном виде;
`off` отключает его.
Если указано `default`, перенаправление включается,
только если `location` обрабатывает запросы через [api](https://angie.software//adc/docs/load_balancer/reference/http/http_api.md#adc-a-api),
[proxy_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-pass), [fastcgi_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_fastcgi.md#adc-fastcgi-pass), [uwsgi_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_uwsgi.md#adc-uwsgi-pass), [scgi_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_scgi.md#adc-scgi-pass),
[memcached_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_memcached.md#adc-memcached-pass), или [grpc_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_grpc.md#adc-grpc-pass).
### chunked_transfer_encoding
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `chunked_transfer_encoding` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | `chunked_transfer_encoding on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запретить формат передачи данных частями (chunked transfer encoding) в HTTP/1.1. Это может понадобиться при использовании программ, не поддерживающих chunked encoding, несмотря на требования стандарта.
### client
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `client` { ... } |
|------------------------------------------------------------------------------------------|--------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Создает специальный контекст `client`
для обработки внутренних HTTP-запросов,
которые Angie выполняет самостоятельно без участия внешних клиентов.
Контекст `client` изолирует служебный трафик
различных модулей Angie от пользовательского трафика,
позволяя дополнительно управлять им.
Внутри этого контекста можно определять только именованные `location`
(с префиксом `@`);
они недоступны для внешних HTTP-запросов
и могут вызываться только программно через внутренние механизмы сервера.
Контекст `client` используется для:
- отправки запросов к центру сертификации в модуле [ACME](https://angie.software//adc/docs/load_balancer/reference/http/http_acme.md#adc-http-acme)
через предопределенный `location @acme`,
который можно дополнительно настроить
с помощью директив модуля [Proxy](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-http-proxy);
- проверки состояния проксируемых серверов
через [upstream_probe](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream_probe.md#adc-u-upstream-probe);
- режима [sticky learn](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky) с `remote_action`
в потоковом модуле [Upstream](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-stream-upstream).
Поддержка нескольких блоков `client`
позволяет группировать общие настройки для нескольких блоков `location`
внутри каждого блока,
что помогает избежать дублирования конфигурации.
При этом директивы, указанные в каждом блоке `client`,
наследуются только явно объявленными внутри него блоками `location`.
В частности, поэтому они не влияют на конфигурацию других модулей,
которые неявно используют блок `client` для исходящих запросов
(например, [ACME](https://angie.software//adc/docs/load_balancer/reference/http/http_acme.md#adc-http-acme)).
Пример использования нескольких блоков `client`
с наследованием настроек:
```nginx
client {
proxy_set_header Host docker.example.com;
proxy_set_header Authorization "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==";
location @docker_events {
}
location @docker_containers {
}
}
client {
proxy_method GET;
proxy_set_header Host backend.example.com;
proxy_set_header X-Real-IP $remote_addr;
location @health_check {
proxy_pass http://upstream-server/health;
}
}
```
#### NOTE
Здесь допускаются те же директивы,
что и в обычных `location`,
однако реально работают только обработчики контента
(например, [autoindex](https://angie.software//adc/docs/load_balancer/reference/http/http_autoindex.md#adc-autoindex))
и переменных (например, [map](https://angie.software//adc/docs/load_balancer/reference/http/http_map.md#adc-map)),
а также директивы, которые сами порождают запросы,
например `upstream_probe`.
Директивы, работающие на других
[стадиях обработки запроса](https://angie.software//adc/docs/load_balancer/reference/processing.md#adc-http-sessions)
(например, [Limit Req](https://angie.software//adc/docs/load_balancer/reference/http/http_limit_req.md#adc-http-limit-req), [auth_request](https://angie.software//adc/docs/load_balancer/reference/http/http_auth_request.md#adc-auth-request),
[try_files](#adc-try-files) и т. д.),
здесь не работают.
### client_body_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_buffer_size` размер; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `client_body_buffer_size 8k|16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает размер буфера для чтения тела запроса клиента. Если тело запроса больше заданного буфера, то все тело запроса или только его часть записывается [во временный файл](https://angie.software//angie/docs/configuration/modules/http/index.md#client-body-temp-path). По умолчанию размер одного буфера равен двум размерам страницы. На x86, других 32-битных платформах и x86-64 это 8K. На других 64-битных платформах это обычно 16K.
### client_body_in_file_only
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_in_file_only` `on` | `clean` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------------------|
| По умолчанию | `client_body_in_file_only off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, сохранять ли все тело запроса клиента в файл. Директиву можно использовать для отладки и при использовании переменной [$request_body_file](#adc-v-request-body-file).
| `on` | временные файлы по окончании обработки запроса не удаляются |
|---------|------------------------------------------------------------------------------|
| `clean` | разрешает удалять временные файлы, оставшиеся по окончании обработки запроса |
### client_body_in_single_buffer
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_in_single_buffer` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| По умолчанию | `client_body_in_single_buffer off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, сохранять ли все тело запроса клиента в одном буфере. Директива рекомендуется при использовании переменной [$request_body](https://angie.software//angie/docs/configuration/modules/http/index.md#v-request-body) для уменьшения требуемого числа операций копирования.
### client_body_temp_path
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `client_body_temp_path` путь [уровень1 [уровень2 [уровень3]]]; |
|------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|
| По умолчанию | `client_body_temp_path client_body_temp;` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | http, server, location |
Задает каталог для хранения временных файлов с телами запросов клиентов. В каталоге может использоваться иерархия подкаталогов до трех уровней. Например, при такой конфигурации
```nginx
client_body_temp_path /spool/angie/client_temp 1 2;
```
путь к временному файлу будет следующего вида:
```nginx
/spool/angie/client_temp/7/45/00000123457
```
### client_body_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_timeout` время; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `client_body_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при чтении тела запроса клиента. Таймаут устанавливается не на всю передачу тела запроса, а только между двумя последовательными операциями чтения. Если по истечении этого времени клиент ничего не передаст, обработка запроса прекращается с ошибкой 408 (Request Time-out).
### client_header_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `client_header_buffer_size` размер; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `client_header_buffer_size 1k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает размер буфера для чтения заголовка запроса клиента. Для большинства запросов достаточно буфера размером в 1K байт. Однако если в запросе есть длинные cookies, или же запрос пришел от WAP-клиента, то он может не поместиться в 1K. Поэтому, если строка запроса или поле заголовка запроса не помещаются полностью в этот буфер, то выделяются буферы большего размера, задаваемые директивой [large_client_header_buffers](#adc-large-client-header-buffers).
Если директива указана на уровне [server](#adc-server), то может использоваться значение из сервера по умолчанию. Подробнее см. в разделе [Выбор виртуального сервера](https://angie.software//angie/docs/configuration/processing.md#request-processing).
### client_header_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `client_header_timeout` время; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `client_header_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает таймаут при чтении заголовка запроса клиента. Если по истечении этого времени клиент не передаст полностью заголовок, обработка запроса прекращается с ошибкой 408 (Request Time-out).
### client_max_body_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `client_max_body_size` размер; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `client_max_body_size 1m;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает максимально допустимый размер тела запроса клиента. Если размер больше заданного, то клиенту возвращается ошибка 413 (Request Entity Too Large). Следует иметь в виду, что браузеры не умеют корректно показывать эту ошибку.
| `0` | отключает проверку размера тела запроса клиента |
|-------|---------------------------------------------------|
### connection_pool_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `connection_pool_size` размер; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `connection_pool_size 256` | `512;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет производить точную настройку выделения памяти под конкретные соединения. Эта директива не оказывает существенного влияния на производительность, и ее не следует использовать. По умолчанию:
| `256` (байт) | на 32-битных платформах |
|----------------|---------------------------|
| `512` (байт) | на 64-битных платформах |
### default_type
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `default_type` mime-тип; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `default_type text/plain;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает MIME-тип ответов по умолчанию. Соответствие расширений имен файлов MIME-типу ответов задается с помощью директивы [types](#adc-types).
### directio
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `directio` размер | `off`; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `directio off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает использовать флаги `O_DIRECT` (FreeBSD, Linux), `F_NOCACHE` (macOS) или функцию `directio()` (Solaris) при чтении файлов, размер которых больше либо равен указанному. Директива автоматически запрещает использование [sendfile](#adc-sendfile) для данного запроса. Рекомендуется использовать для больших файлов:
```nginx
directio 4m;
```
или при использовании [aio](#adc-aio) в Linux.
### directio_alignment
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `directio_alignment` размер; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `directio_alignment 512;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Устанавливает выравнивание для [directio](#adc-directio). В большинстве случаев достаточно 512-байтового выравнивания, однако при использовании XFS под Linux его нужно увеличить до 4K.
### disable_symlinks
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `disable_symlinks` `off`;
`disable_symlinks` `on` | `if_not_owner` [`from=`часть]; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|
| По умолчанию | `disable_symlinks off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, как следует поступать с символическими ссылками при открытии файлов:
| `off` | Символические ссылки в пути допускаются и не проверяются. Это стандартное поведение. |
|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `on` | Если любой компонент пути является символической ссылкой, доступ к файлу запрещается. |
| `if_not_owner` | Доступ к файлу запрещается, если любой компонент пути является символической ссылкой, а ссылка и объект, на который она ссылается, имеют разных владельцев. |
| `from=`часть | При проверке символических ссылок (параметры `on` и `if_not_owner`) обычно проверяются все компоненты пути. Можно не проверять символические ссылки в начальной части пути, указав дополнительно параметр `from=часть`. В этом случае символические ссылки проверяются лишь начиная с компонента пути, который следует за заданной начальной частью. Если значение не является начальной частью проверяемого пути, путь проверяется целиком, как если бы этот параметр не был указан вовсе. Если значение целиком совпадает с именем файла, символические ссылки не проверяются. В значении параметра можно использовать переменные. |
Пример:
```nginx
disable_symlinks on from=$document_root;
```
Эта директива доступна только на системах, в которых есть интерфейсы `openat()` и `fstatat()`. К таким системам относятся современные версии FreeBSD, Linux и Solaris.
#### WARNING
Параметры `on` и `if_not_owner` требуют дополнительных затрат на обработку.
На системах, не поддерживающих операцию открытия каталогов только для поиска, для использования этих параметров требуется, чтобы рабочие процессы имели право читать все проверяемые каталоги.
#### NOTE
Модули [AutoIndex](https://angie.software//angie/docs/configuration/modules/http/http_autoindex.md#http-autoindex), [Random Index](https://angie.software//angie/docs/configuration/modules/http/http_random_index.md#http-random-index) и [DAV](https://angie.software//angie/docs/configuration/modules/http/http_dav.md#http-dav) в настоящий момент игнорируют эту директиву.
### early_hints
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `early_hints` строка ...; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает условия, при которых ответ с кодом "103 Early Hints" будет передан клиенту. Такой ответ может быть возвращен проксируемыми и gRPC-бэкендами. Если значение хотя бы одного из строковых параметров непустое и не равно `0`, то ответ будет передан:
```nginx
map $http_sec_fetch_mode $early_hints {
navigate $http2$http3;
}
server {
...
location / {
early_hints $early_hints;
proxy_pass http://example.com;
}
}
```
### error_page
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `error_page` код ... [=[ответ]] uri; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Задает URI, который будет показываться для указанных ошибок. В значении uri можно использовать переменные.
Пример:
```nginx
error_page 404 /404.html;
error_page 500 502 503 504 /50x.html;
```
При этом делается внутреннее перенаправление на указанный uri, а метод запроса клиента меняется на "GET" (для всех методов, отличных от "GET" и "HEAD").
Кроме того, можно поменять код ответа на другой, используя синтаксис вида `=ответ`, например:
```nginx
error_page 404 =200 /empty.gif;
```
Если ошибочный ответ обрабатывается проксированным сервером или FastCGI/uwsgi/SCGI/gRPC-сервером, и этот сервер может вернуть разные коды ответов, например, 200, 302, 401 или 404, то можно выдавать возвращаемый им код:
```nginx
error_page 404 = /404.php;
```
Если при внутреннем перенаправлении не нужно менять URI и метод, то можно передать обработку ошибки в именованный `location`:
```nginx
location / {
error_page 404 = @fallback;
}
location @fallback {
proxy_pass http://backend;
}
```
#### NOTE
Если при обработке uri происходит ошибка, клиенту возвращается ответ с кодом последней случившейся ошибки.
Также существует возможность использовать перенаправления URL для обработки ошибок:
```nginx
error_page 403 http://example.com/forbidden.html;
error_page 404 =301 http://example.com/notfound.html;
```
В этом случае по умолчанию клиенту возвращается код ответа 302. Его можно изменить только на один из кодов ответа, относящихся к перенаправлениям (301, 302, 303, 307 и 308).
### etag
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `etag` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | `etag on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает автоматическую генерацию поля `ETag` заголовка ответа для статических ресурсов.
### http
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `http` { ... } |
|------------------------------------------------------------------------------------------|------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | main |
Предоставляет контекст конфигурационного файла, в котором указываются директивы HTTP-сервера.
### if_modified_since
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `if_modified_since` `off` | `exact` | `before`; |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| По умолчанию | `if_modified_since exact;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, как сравнивать время модификации ответа с временем в поле `If-Modified-Since` заголовка запроса:
| `off` | ответ всегда считается изменившимся |
|----------|------------------------------------------------------------------------------------------------------------|
| `exact` | точное совпадение |
| `before` | время модификации ответа меньше или равно времени, заданному в поле `If-Modified-Since` заголовка запроса |
### ignore_invalid_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ignore_invalid_headers` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `ignore_invalid_headers on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Если включено, Angie игнорирует поля заголовка с недопустимыми именами. Допустимыми считаются имена, состоящие из английских букв, цифр, дефисов и возможно знаков подчеркивания (последнее контролируется директивой [underscores_in_headers](#adc-underscores-in-headers)).
Если директива указана на уровне [server](#adc-server), то может использоваться значение из сервера по умолчанию.
### internal
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `internal;` |
|------------------------------------------------------------------------------------------|---------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Указывает, что `location` может использоваться только для внутренних
запросов. Для внешних запросов будет возвращаться ошибка 404 (Not Found) в
контексте данного `location`, что позволяет перенаправить такие запросы с
помощью [error_page](https://angie.software//angie/docs/configuration/modules/http/index.md#error-page). Внутренними запросами являются:
* запросы, перенаправленные директивами [error_page](https://angie.software//angie/docs/configuration/modules/http/index.md#error-page),
[index](https://angie.software//adc/docs/load_balancer/reference/http/http_index.md#adc-index), [random_index](https://angie.software//adc/docs/load_balancer/reference/http/http_random_index.md#adc-random-index) и [try_files](#adc-try-files);
* запросы, перенаправленные с помощью поля `X-Accel-Redirect` заголовка
ответа вышестоящего сервера;
* подзапросы, формируемые командой `include virtual` модуля [SSI](https://angie.software//angie/docs/configuration/modules/http/http_ssi.md#http-ssi), директивами модуля [Addition](https://angie.software//angie/docs/configuration/modules/http/http_addition.md#http-addition),
а также директивами [auth_request](https://angie.software//adc/docs/load_balancer/reference/http/http_auth_request.md#adc-auth-request) и [mirror](https://angie.software//adc/docs/load_balancer/reference/http/http_mirror.md#adc-mirror);
* запросы, измененные директивой [rewrite](https://angie.software//adc/docs/load_balancer/reference/http/http_rewrite.md#adc-rewrite).
Пример:
```nginx
error_page 404 /404.html;
location = /404.html {
internal;
}
```
Благодаря тому, что ошибка 404 возвращается в контексте `location` с
директивой `internal`, можно перенаправлять внешние запросы в другое
место. Это позволяет использовать один префикс как для внешнего, так и для
внутреннего запроса, но с разной обработкой, например:
```nginx
location /path {
internal;
error_page 404 =@external;
proxy_pass https://internal;
}
location @external {
proxy_pass https://external;
}
```
Здесь внешний запрос `GET /path` будет проксирован на
`https://external/path`, а такой же внутренний запрос будет проксирован на
`https://internal/path`.
#### NOTE
Для предотвращения зацикливания, которое может возникнуть при использовании
некорректных конфигураций, количество внутренних перенаправлений ограничено
десятью. По достижении этого ограничения будет возвращена ошибка 500
(Internal Server Error). В таком случае в лог-файле ошибок можно увидеть
сообщение `rewrite or internal redirection cycle`.
### keepalive_disable
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `keepalive_disable` `none` | браузер ...; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | `keepalive_disable msie6;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Запрещает соединения keep-alive с некорректно ведущими себя браузерами. Параметры браузер указывают, на какие браузеры это распространяется.
| `none` | разрешает соединения keep-alive со всеми браузерами |
|----------|----------------------------------------------------------------------------------------------|
| `msie6` | запрещает соединения keep-alive со старыми версиями MSIE после получения запроса POST |
| `safari` | запрещает соединения keep-alive с Safari и подобными им браузерами на macOS и подобных ей ОС |
### 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) | http, server, location |
Задает максимальное число запросов, которые можно сделать по одному keep-alive соединению. После того, как сделано максимальное число запросов, соединение закрывается.
Периодическое закрытие соединений необходимо для освобождения памяти, выделенной под конкретные соединения. Поэтому использование слишком большого максимального числа запросов может приводить к чрезмерному потреблению памяти и не рекомендуется.
### 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) | http, server, location |
Ограничивает максимальное время, в течение которого могут обрабатываться запросы в рамках соединения keep-alive. По достижении заданного времени соединение закрывается после обработки очередного запроса.
### keepalive_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `keepalive_timeout` таймаут [заголовок_таймаута]; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------|
| По умолчанию | `keepalive_timeout 75s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
| таймаут | задает время, в течение которого keep-alive соединение с клиентом не будет закрыто со стороны сервера |
|-----------|---------------------------------------------------------------------------------------------------------|
| `0` | запрещает keep-alive соединения с клиентами |
Второй, *необязательный*, параметр задает значение в поле `Keep‑Alive: timeout=время` заголовка ответа. Два параметра могут отличаться друг от друга.
Поле `Keep-Alive: timeout=время` заголовка понимают Mozilla и Konqueror. MSIE сам закрывает keep-alive соединение примерно через 60 секунд.
### large_client_header_buffers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `large_client_header_buffers` количество размер; |
|------------------------------------------------------------------------------------------|----------------------------------------------------|
| По умолчанию | `large_client_header_buffers 4 8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает максимальное число и размер буферов для чтения большого заголовка запроса клиента. Строка запроса не должна превышать размера одного буфера, иначе клиенту возвращается ошибка 414 (Request-URI Too Large). Поле заголовка запроса также не должно превышать размера одного буфера, иначе клиенту возвращается ошибка 400 (Bad Request). Буферы выделяются только по мере необходимости. По умолчанию размер одного буфера равен 8K байт. Если по окончании обработки запроса соединение переходит в состояние keep-alive, эти буферы освобождаются.
Если директива указана на уровне [server](#adc-server), то может использоваться значение из сервера по умолчанию.
### limit_except
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_except` метод1 [метод2...] { ... }; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Ограничивает HTTP-методы, доступные внутри location. Параметр метод может быть
одним из `GET`, `HEAD`, `POST`, `PUT`, `DELETE`,
`MKCOL`, `COPY`, `MOVE`, `OPTIONS`, `PROPFIND`,
`PROPPATCH`, `LOCK`, `UNLOCK` или `PATCH`. Если разрешен
метод `GET`, то метод `HEAD` также будет разрешен. Доступ к
остальным методам может быть ограничен при помощи директив модулей [Access](https://angie.software//angie/docs/configuration/modules/http/http_access.md#http-access) и [Auth Basic](https://angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic).
```nginx
limit_except GET {
allow 192.168.1.0/32;
deny all;
}
```
#### NOTE
Ограничение в примере действует для всех методов,
**кроме** `GET` и `HEAD`.
### limit_rate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_rate` скорость; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `limit_rate 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Ограничивает скорость передачи ответа клиенту. Скорость задается в байтах в секунду. Значение `0` отключает ограничение скорости. Ограничение устанавливается на запрос, поэтому, если клиент одновременно откроет два соединения, суммарная скорость будет вдвое выше заданного ограничения.
В значении параметра можно использовать переменные. Это может быть полезно в случаях, когда скорость нужно ограничивать в зависимости от какого-либо условия:
```nginx
map $slow $rate {
1 4k;
2 8k;
}
limit_rate $rate;
```
Ограничение скорости можно также задать в переменной [$limit_rate](#adc-v-limit-rate), однако использовать данный метод не рекомендуется:
```nginx
server {
if ($slow) {
set $limit_rate 4k;
}
}
```
Кроме того, ограничение скорости может быть задано в поле `X-Accel-Limit-Rate` заголовка ответа проксированного сервера. Эту возможность можно запретить с помощью директив [proxy_ignore_headers](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-ignore-headers), [fastcgi_ignore_headers](https://angie.software//adc/docs/load_balancer/reference/http/http_fastcgi.md#adc-fastcgi-ignore-headers), [uwsgi_ignore_headers](https://angie.software//adc/docs/load_balancer/reference/http/http_uwsgi.md#adc-uwsgi-ignore-headers) и [scgi_ignore_headers](https://angie.software//adc/docs/load_balancer/reference/http/http_scgi.md#adc-scgi-ignore-headers).
### limit_rate_after
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_rate_after` размер; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `limit_rate_after 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Задает начальный объем данных, после передачи которого начинает ограничиваться скорость передачи ответа клиенту. В значении параметра можно использовать переменные.
Пример:
```nginx
location /flv/ {
flv;
limit_rate_after 500k;
limit_rate 50k;
}
```
### lingering_close
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `lingering_close` `on` | `always` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | `lingering_close on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Управляет закрытием соединений с клиентами.
| `on` | Angie будет [ждать](https://angie.software//angie/docs/configuration/modules/http/index.md#lingering-timeout) и [обрабатывать](https://angie.software//angie/docs/configuration/modules/http/index.md#lingering-time) дополнительные данные, поступающие от клиента, перед полным закрытием соединения, но только если эвристика указывает на то, что клиент может еще послать данные. |
|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `always` | Angie всегда будет ждать и обрабатывать дополнительные данные, поступающие от клиента. |
| `off` | Angie не будет ждать поступления дополнительных данных и сразу же закроет соединение. Это поведение нарушает протокол и поэтому не должно использоваться без необходимости. |
Для управления закрытием HTTP/2-соединений директива должна быть задана на уровне [server](#adc-server).
### lingering_time
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `lingering_time` время; |
|------------------------------------------------------------------------------------------|---------------------------|
| По умолчанию | `lingering_time 30s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если действует [lingering_close](#adc-lingering-close), эта директива задает максимальное время, в течение которого Angie будет обрабатывать (читать и игнорировать) дополнительные данные, поступающие от клиента. По прошествии этого времени соединение будет закрыто, даже если будут еще данные.
### lingering_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `lingering_timeout` время; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `lingering_timeout 5s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если действует [lingering_close](#adc-lingering-close), эта директива задает максимальное время
ожидания поступления дополнительных данных от клиента. Если в течение этого
времени данные не были получены, соединение закрывается. В противном случае
данные читаются и игнорируются, и Angie снова ждет поступления данных. Цикл
"ждать-читать-игнорировать" повторяется, но не дольше чем задано директивой
[lingering_time](#adc-lingering-time).
При постепенном завершении клиентские постоянные соединения закрываются только в
случае, если они неактивны не менее времени, заданного в
`lingering_timeout`.
#### NOTE
В nginx аналогичная директива называется [keepalive_min_timeout](https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_min_timeout).
### listen
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `listen` адрес[:порт] [`default_server`] [`ssl`] [http2 | `quic`] [`proxy_protocol`] [`setfib=`число] [`fastopen=`число] [`backlog=`число] [`rcvbuf=`размер] [`sndbuf=`размер] [`accept_filter=`фильтр] [`deferred`] [`bind`] [`ipv6only=``on` | `off`] [`reuseport`] [`so_keepalive=`on|off|[`keepidle`]:[`keepintvl`]:[`keepcnt`]];
`listen` порт [`default_server`] [`ssl`] [http2 | `quic`] [`proxy_protocol`] [`setfib=`число] [`fastopen=`число] [`backlog=`число] [`rcvbuf=`размер] [`sndbuf=`размер] [`accept_filter=`фильтр] [`deferred`] [`bind`] [`ipv6only=``on` | `off`] [`reuseport`] [`so_keepalive=`on|off|[`keepidle`]:[`keepintvl`]:[`keepcnt`]];
`listen` unix:путь [`default_server`] [`ssl`] [http2 | `quic`] [`proxy_protocol`] [`backlog=`число] [`rcvbuf=`размер] [`sndbuf=`размер] [`accept_filter=`фильтр] [`deferred`] [`bind`] [`so_keepalive=`on|off|[`keepidle`]:[`keepintvl`]:[`keepcnt`]]; |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `listen *:80` | `*:8000;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server |
Задает адрес и порт для прослушивающего сокета или путь к UNIX-доменному
сокету, на котором сервер будет принимать запросы.
Адрес также может быть именем хоста, например:
```nginx
listen 127.0.0.1:8000;
listen 127.0.0.1;
listen 8000;
listen *:8000;
listen localhost:8000;
```
IPv6-адреса указываются в квадратных скобках:
```nginx
listen [::]:8000;
listen [::1];
```
UNIX-доменные сокеты задаются с префиксом `unix:`:
```nginx
listen unix:/var/run/angie.sock;
```
Можно указать адрес и порт вместе, только адрес или только порт.
Если какие-либо параметры опущены, применяются следующие правила:
- Если указан только адрес, используется порт 80.
- Если указан только порт,
Angie будет слушать на всех доступных интерфейсах IPv4 (и IPv6, если включен).
Стоящий первым блок `server` на этом порту будет сервером по умолчанию
для запросов с несопоставленным заголовком `Host`.
- Если директива не указана вовсе, Angie использует `*:80`,
если запущен с правами суперпользователя,
или `*:8000` в противном случае.
| `default_server` | сервер, в котором указан этот параметр,
будет сервером по умолчанию для указанной пары адрес:порт
(вместе они образуют *cлушающий сокет*).
Если же директив с параметром `default_server` нет,
сервером по умолчанию для слущающего сокета
будет первый в конфигурации сервер, обслуживающий этот сокет. |
|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `ssl` | указывает на то, что все соединения, принимаемые на данном слушающем сокете, должны работать в режиме SSL. Это позволяет задать [компактную конфигурацию](https://angie.software//angie/docs/configuration/ssl.md#compact-server) для сервера, работающего сразу в двух режимах — HTTP и HTTPS. |
| `http2` | позволяет принимать на слушающем сокете HTTP/2-соединения. Обычно, чтобы это работало, следует также указать параметр `ssl`, однако Angie можно также настроить и на прием HTTP/2-соединений без SSL. |
| `quic` | позволяет принимать на этом порту QUIC-соединения.
Для использования этой опции в Angie
должен быть включен и настроен модуль [HTTP3](https://angie.software//angie/docs/configuration/modules/http/http_v3.md#http-v3).
Когда `quic` включен,
также можно указать `reuseport`,
чтобы использовать несколько рабочих процессов. |
| `proxy_protocol` | указывает на то, что все соединения, принимаемые на данном слушающем сокете, должны использовать протокол PROXY. |
В директиве `listen` можно также указать несколько дополнительных
параметров, специфичных для связанных с сокетами системных вызовов. Следующие
параметры можно задать в любой директиве `listen`, но только один раз для
каждого слушающего сокета:
| `setfib=`число | задает таблицу маршрутизации, FIB (параметр `SO_SETFIB`) для слушающего сокета. В настоящий момент это работает только на FreeBSD. |
|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `fastopen=`число | включает "TCP Fast Open" для слушающего сокета и ограничивает максимальную длину очереди соединений, которые еще не завершили процесс трехстороннего рукопожатия.
#### WARNING
Не включайте "TCP Fast Open", не убедившись, что сервер может адекватно обрабатывать многократное получение одного и того же SYN-пакета с данными. |
| `backlog=`число | задает параметр `backlog` в вызове `listen()`, который ограничивает максимальный размер очереди ожидающих приема соединений. По умолчанию `backlog` устанавливается равным -1 для FreeBSD, DragonFly BSD и macOS, и 511 для других платформ. |
| `rcvbuf=`размер | задает размер буфера приема (параметр `SO_RCVBUF`) для слушающего сокета. |
| `sndbuf=`размер | задает размер буфера передачи (параметр `SO_SNDBUF`) для слушающего сокета. |
| `accept_filter=`фильтр | задает название accept-фильтра (параметр `SO_ACCEPTFILTER`) для слушающего сокета, который включается для фильтрации входящих соединений перед передачей их в `accept()`. Работает только на FreeBSD и NetBSD 5.0+. Можно использовать два фильтра: `dataready` и `httpready`. |
| `deferred` | указывает использовать отложенный `accept()` (параметр `TCP_DEFER_ACCEPT` сокета) на Linux. |
| `bind` | указывает, что для данного слушающего сокета нужно делать `bind()` отдельно. Это нужно потому, что если описаны несколько директив `listen` с одинаковым портом, но разными адресами, и одна из директив `listen` слушает на всех адресах для данного порта (`*:порт`), то Angie сделает `bind()` только на `*:порт`. Необходимо заметить, что в этом случае для определения адреса, на который пришло соединение, делается системный вызов `getsockname()`. Если же используются параметры `setfib`, `fastopen`, `backlog`, `rcvbuf`, `sndbuf`, `accept_filter`, `deferred`, `ipv6only`, `reuseport` или `so_keepalive`, то для данной пары адрес:порт всегда делается отдельный вызов `bind()`. |
| `ipv6only=on` | `off` | определяет (через параметр сокета `IPV6_V6ONLY`), будет ли слушающий на wildcard-адресе [::] IPv6-сокет принимать только IPv6-соединения, или же одновременно IPv6- и IPv4-соединения.
По умолчанию параметр включен. Установить его можно только один раз на старте. |
| `reuseport` | указывает, что нужно создавать отдельный слушающий сокет для каждого рабочего процесса (через параметр сокета `SO_REUSEPORT` для Linux 3.9+ и DragonFly BSD или `SO_REUSEPORT_LB` для FreeBSD 12+), позволяя ядру распределять входящие соединения между рабочими процессами. В настоящий момент это работает только на Linux 3.9+, DragonFly BSD и FreeBSD 12+.
#### WARNING
Ненадлежащее использование параметра `reuseport`
может быть небезопасно. |
| `multipath` | включает прием соединений по протоколу [Multipath TCP](https://en.wikipedia.org/wiki/Multipath_TCP) (MPTCP),
поддерживаемому в ядре Linux с версии 5.6.
Параметр **несовместим** с `quic`. |
`so_keepalive=on` | `off` | [`keepidle`]:[`keepintvl`]:[`keepcnt`]
Конфигурирует для слушающего сокета поведение "TCP keepalive".
| `''` | если параметр опущен, для сокета будут действовать настройки операционной системы |
|--------|-------------------------------------------------------------------------------------|
| `on` | для сокета включается параметр `SO_KEEPALIVE` |
| `off` | для сокета параметр `SO_KEEPALIVE` выключается |
Некоторые операционные системы поддерживают настройку параметров "TCP keepalive" на уровне сокета посредством параметров `TCP_KEEPIDLE`, `TCP_KEEPINTVL` и `TCP_KEEPCNT`. На таких системах (в настоящее время это Linux, NetBSD, Dragonfly, FreeBSD и macOS) их можно сконфигурировать с помощью параметров `keepidle`, `keepintvl` и `keepcnt`. Один или два параметра могут быть опущены, в таком случае для соответствующего параметра сокета будут действовать стандартные системные настройки. Например,
```nginx
so_keepalive=30m::10
```
установит таймаут бездействия (`TCP_KEEPIDLE`) в 30 минут, для интервала проб (`TCP_KEEPINTVL`) будет действовать стандартная системная настройка, а счетчик проб (`TCP_KEEPCNT`) будет равен 10.
Пример:
```nginx
listen 127.0.0.1 default_server accept_filter=dataready backlog=1024;
```
### location
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `location` ([ = | ~ | ~\* | ^~ ] uri | `@имя`)+ { ... } |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location |
Устанавливает конфигурацию в зависимости от того, соответствует ли URI запроса
какому-либо из выражений сопоставления.
Для сопоставления используется URI запроса в нормализованном виде, после
декодирования текста, заданного в виде `%XX`, преобразования относительных
элементов пути "." и ".." в реальные и возможной [замены](https://angie.software//angie/docs/configuration/modules/http/index.md#merge-slashes)
двух и более подряд идущих косых черт на одну.
Задать `location` можно префиксной строкой или регулярным выражением.
Регулярные выражения задаются с модификатором:
| `~*` | Для поиска совпадения без учета регистра символов |
|--------|-----------------------------------------------------|
| `~` | С учетом регистра |
Чтобы найти `location`, соответствующий запросу, вначале проверяются
`location`'ы, заданные префиксными строками (префиксные `location`'ы). Среди
них ищется `location` с совпадающим префиксом максимальной длины и
запоминается.
#### NOTE
Для операционных систем, нечувствительных к регистру символов, таких как
macOS, сравнение с префиксными строками производится без учета регистра.
Однако сравнение ограничено только однобайтными `locale`'ями.
Затем проверяются регулярные выражения в порядке их следования в
конфигурационном файле. Проверка регулярных выражений прекращается после
первого же совпадения, и используется соответствующая конфигурация. Если
совпадение с регулярным выражением не найдено, то используется конфигурация
запомненного ранее префиксного `location`'а.
За некоторыми исключениями, о которых говорится ниже,
блоки `location` могут быть вложенными.
Регулярные выражения могут создавать группы захвата, которые затем можно
использовать в других директивах.
Если у совпавшего префиксного `location`'а указан модификатор `^~`,
то регулярные выражения не проверяются.
Кроме того, с помощью модификатора `=` можно задать точное совпадение URI и
`location`. При точном совпадении поиск сразу же прекращается. Например, если
запрос `/` случается часто, можно ускорить обработку таких запросов, указав
`location =/`, так как поиск прекратится после первого же сравнения. Такой
`location` не может иметь вложенные `location`, так как он задает полное
совпадение.
Пример:
```nginx
location =/ {
#конфигурация А
}
location / {
#конфигурация Б
}
location /documents/ {
#конфигурация В
}
location ^~/images/ {
#конфигурация Г
}
location ~*\.(gif|jpg|jpeg)$ {
#конфигурация Д
}
```
- Для запроса `/` будет выбрана конфигурация А,
- для запроса `/index.html` — конфигурация Б,
- для запроса `/documents/document.html` — конфигурация В,
- для запроса `/images/1.gif` — конфигурация Г,
- а для запроса `/documents/1.jpg` — конфигурация Д.
#### NOTE
Если префиксный `location` задан с косой чертой в конце
и включена директива [auto_redirect](#adc-auto-redirect), происходит следующее:
На запрос с URI без косой черты в конце, в остальном совпадающий с префиксом,
будет возвращено постоянное перенаправление с кодом 301, указывающее
на URI запроса с добавленной в конце косой чертой.
Если задать `location` с точным совпадением URI,
перенаправление не используется:
```nginx
location /user/ {
proxy_pass http://user.example.com;
}
location =/user {
proxy_pass http://login.example.com;
}
```
Префикс `@` задает *именованный* `location`. Такой `location` не используется
при обычной обработке запросов, а предназначен только для перенаправления в
него запросов. Такие `location` не могут быть вложенными и не могут содержать
вложенные `location`.
#### Комбинированные `location`
Для удобства несколько `location` с одинаковой конфигурацией можно записать
компактно, перечислив в одном `location` сразу несколько выражений
сопоставления и задав для них единую конфигурацию. Такие `location` называются
*комбинированными*.
Если, например, предположить, что в предыдущем примере конфигурации А, Г и Д
совпадают, то их можно записать с помощью комбинированного `location`:
```nginx
location =/
^~/images/
~*\.(gif|jpg|jpeg)$ {
#общая конфигурация
}
```
Именованный `location` также может быть частью комбинированного:
```nginx
location =/
@named_combined {
#...
}
```
#### WARNING
В комбинированных `location` между модификатором выражения сопоставления и
самим выражением не может стоять пробел. Правильно: `location
~*/match(ing|es|er)$ *...*`.
#### NOTE
Сейчас комбинированные `location` не могут **непосредственно** содержать
директивы `proxy_pass`, в которых задан URI, а также `api` и `alias`.
При этом такие директивы можно использовать в других `location`,
вложенных в комбинированный.
### log_not_found
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `log_not_found` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `log_not_found on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает записывать в [error_log](https://angie.software//adc/docs/load_balancer/reference/core.md#adc-error-log) ошибки о том, что файл не найден.
### log_subrequest
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `log_subrequest` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `log_subrequest off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает записывать в [access_log](https://angie.software//adc/docs/load_balancer/reference/http/http_log.md#adc-access-log) подзапросы.
### max_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `max_headers` число; |
|------------------------------------------------------------------------------------------|------------------------|
| Значение по умолчанию | `max_headers 1000;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Устанавливает максимальное количество полей заголовков запроса клиента.
При превышении предела клиенту возвращается ошибка `400 (Bad Request)`.
Если эта директива задана на уровне [server](#adc-server),
может использоваться значение с сервера по умолчанию.
Дополнительные сведения см. в разделе [Выбор виртуального сервера](https://angie.software//adc/docs/load_balancer/reference/processing.md#adc-virtual-server-selection).
### max_ranges
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `max_ranges` число; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает максимальное допустимое число диапазонов в запросах с указанием диапазона запрашиваемых байт (byte-range requests). Запросы, превышающие указанное ограничение, обрабатываются как если бы они не содержали указания диапазонов. По умолчанию число диапазонов не ограничено.
| `0` | полностью запрещает поддержку диапазонов |
|-------|--------------------------------------------|
### merge_slashes
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `merge_slashes` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `merge_slashes on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает или запрещает преобразование URI путем замены двух и более подряд идущих косых черт ("/") на одну.
Необходимо иметь в виду, что это преобразование необходимо для корректной проверки префиксных строк и регулярных выражений. Если его не делать, то запрос `//scripts/one.php` не попадет в
```nginx
location /scripts/ { }
```
и может быть обслужен как статический файл. Поэтому он преобразуется к виду `/scripts/one.php`.
Запрет преобразования может понадобиться, если в URI используются имена, закодированные методом `base64`, в котором задействован символ "/". Однако из соображений безопасности лучше избегать отключения преобразования.
Если директива указана на уровне [server](#adc-server), то может использоваться значение из сервера по умолчанию.
### msie_padding
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `msie_padding` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `msie_padding on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает добавлять в ответы для MSIE со статусом больше 400 комментарий для увеличения размера ответа до 512 байт.
### msie_refresh
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `msie_refresh` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `msie_refresh off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает выдавать для MSIE клиентов refresh'ы вместо перенаправлений.
### open_file_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `open_file_cache` `off`;
`open_file_cache` `max=``N` [`inactive=`время]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| По умолчанию | `open_file_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает кэш, в котором могут храниться:
* дескрипторы открытых файлов, информация об их размерах и времени модификации;
* информация о существовании каталогов;
* информация об ошибках поиска файла — "нет файла", "нет прав на чтение" и тому подобное.
Кэширование ошибок нужно разрешить отдельно директивой [open_file_cache_errors](#adc-open-file-cache-errors).
| `max` | задает максимальное число элементов в кэше; при переполнении кэша удаляются наименее востребованные элементы (LRU) |
|------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
| `inactive` | задает время, после которого элемент кэша удаляется, если к нему не было обращений в течение этого времени.
По умолчанию: 60 секунд. |
| `off` | запрещает кэш. |
Пример:
```nginx
open_file_cache max=1000 inactive=20s;
open_file_cache_valid 30s;
open_file_cache_min_uses 2;
open_file_cache_errors on;
```
### open_file_cache_errors
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `open_file_cache_errors` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `open_file_cache_errors off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает кэширование ошибок поиска файлов в [open_file_cache](#adc-open-file-cache).
### open_file_cache_events
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `open_file_cache_events` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `open_file_cache_events off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает использование событий ядра для проверки актуальности элементов [open_file_cache](#adc-open-file-cache). Директива работает только с методом [kqueue](https://angie.software//angie/docs/configuration/processing.md#kqueue). Обратите внимание, что только NetBSD 2.0+ и FreeBSD 6.0+ поддерживают события для произвольных типов файловых систем; остальные операционные системы поддерживают события только для основных файловых систем, таких как UFS или FFS.
### open_file_cache_min_uses
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `open_file_cache_min_uses` число; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `open_file_cache_min_uses 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает минимальное число обращений к файлу в течение времени, заданного параметром inactive директивы [open_file_cache](#adc-open-file-cache), необходимых для того, чтобы дескриптор файла оставался открытым в кэше.
### open_file_cache_valid
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `open_file_cache_valid` время; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `open_file_cache_valid 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет время, через которое следует проверять актуальность информации об элементе в [open_file_cache](#adc-open-file-cache).
### output_buffers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `output_buffers` число размер; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `output_buffers 2 32k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число и размер буферов, используемых при чтении ответа с диска.
### port_in_redirect
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `port_in_redirect` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `port_in_redirect on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает указывать порт в [абсолютных](https://angie.software//angie/docs/configuration/modules/http/index.md#absolute-redirect) перенаправлениях, выдаваемых Angie.
Использование в перенаправлениях основного имени сервера управляется директивой [server_name_in_redirect](#adc-server-name-in-redirect).
### postpone_output
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `postpone_output` размер; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `postpone_output 1460;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если это возможно, то отправка данных клиенту будет отложена пока Angie не накопит по крайней мере указанное количество байт для отправки.
| `0` | запрещает отложенную отправку данных |
|-------|----------------------------------------|
### read_ahead
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `read_ahead` размер; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | `read_ahead 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает ядру размер предчтения при работе с файлами.
На Linux используется системный вызов `posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)`, поэтому параметр размер там игнорируется.
На FreeBSD используется системный вызов `fcntl(O_READAHEAD,` размер ), появившийся во FreeBSD 9.0-CURRENT.
### recursive_error_pages
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `recursive_error_pages` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `recursive_error_pages off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает делать несколько перенаправлений через директиву [error_page](#adc-error-page). Число таких перенаправлений [ограничено](https://angie.software//angie/docs/configuration/modules/http/index.md#internal).
### request_pool_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `request_pool_size` размер; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `request_pool_size 4k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Позволяет производить точную настройку выделения памяти под конкретные запросы. Эта директива не оказывает существенного влияния на производительность, и ее не следует использовать.
### reset_timedout_connection
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `reset_timedout_connection` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | `reset_timedout_connection off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает сброс соединений по таймауту, а также при закрытии соединений с помощью нестандартного кода 444. Сброс делается следующим образом. Перед закрытием сокета для него задается параметр `SO_LINGER` с таймаутом `0`. После этого при закрытии сокета клиенту отсылается `TCP RST`, а вся память, связанная с этим сокетом, освобождается. Это позволяет избежать длительного нахождения уже закрытого сокета в состоянии `FIN_WAIT1` с заполненными буферами.
#### NOTE
соединения keep-alive по истечении таймаута закрываются обычным образом.
### resolver
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `resolver` адрес ... [`valid=`время] [`ipv4=``on` | `off`] [`ipv6=``on` | `off`] [`status_zone=`зона]; |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, upstream |
Задает серверы DNS, используемые для преобразования имен вышестоящих серверов в адреса, например:
```nginx
resolver 127.0.0.53 [::1]:5353;
```
Адрес может быть указан в виде доменного имени или IP-адреса, и необязательного порта.
Если порт не указан, используется порт 53. Серверы DNS опрашиваются циклически.
#### NOTE
Рекомендуется использовать локальный доверенный резолвер, например
`127.0.0.53` (systemd-resolved), а не публичный (например, `8.8.8.8`).
Публичные резолверы раскрывают DNS-запросы третьим сторонам и повышают
риск атак с подменой кэша.
#### NOTE
Значение директивы наследуется вложенными блоками
и может быть переопределено в них при необходимости.
В пределах одного блока допустимо указывать директиву только один раз.
Если она повторяется, действует последнее определение.
По умолчанию Angie кэширует ответы, используя значение TTL из ответа DNS. Если
директива `resolver` не указана и не выполняются динамические DNS-запросы
(например, при использовании фиксированных имен в [Proxy](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-http-proxy) без
переменных), указание резолвера не требуется: имена будут разрешены при запуске
с помощью системного резолвера. Необязательный параметр `valid` позволяет
это переопределить:
| `valid` | *необязательный* параметр, позволяет переопределить срок кэширования ответа |
|-----------|--------------------------------------------------------------------------------|
```nginx
resolver 127.0.0.53 [::1]:5353 valid=30s;
```
По умолчанию Angie будет искать как IPv4-, так и IPv6-адреса при преобразовании имен в адреса.
| `ipv4=off` | запрещает поиск IPv4-адресов |
|--------------|--------------------------------|
| `ipv6=off` | запрещает поиск IPv6-адресов |
| `status_zone` | *необязательный* параметр;
включает сбор метрик запросов и ответов DNS-сервера
в указанной зоне, отображая их в [/status/resolvers/<зона>](https://angie.software//adc/docs/load_balancer/reference/http/http_api.md#adc-api-status-resolvers),
[вкладке «DNS Resolvers»](https://angie.software//angie/docs/configuration/monitoring.md#samp-dns-resolvers-tab)
и в выводе [Prometheus](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus).
Без него эти метрики не собираются, и предупреждение не выводится |
|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### resolver_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `resolver_timeout` время; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `resolver_timeout 30s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, upstream |
Задает таймаут для преобразования имени в адрес, например:
```nginx
resolver_timeout 5s;
```
### error_log_user_tag
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `error_log_user_tag` значение; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, limit_except |
Добавляет тег, зависящий от запроса, в записи [error_log](https://angie.software//adc/docs/load_balancer/reference/core.md#adc-error-log). Значение является
[сложным значением](https://angie.software//angie/docs/configuration/configfile.md#syntax) и может содержать переменные. Директива может
задаваться несколько раз для добавления нескольких тегов. Теги используются в
фильтрах `filter=tag:` директивы [error_log](https://angie.software//adc/docs/load_balancer/reference/core.md#adc-error-log).
### root
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `root` путь; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `root html;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Задает корневой каталог для запросов. Например, при такой конфигурации
```nginx
location /i/ {
root /data/w3;
}
```
в ответ на запрос `/i/top.gif` будет отдан файл `/data/w3/i/top.gif`.
В значении параметра путь можно использовать переменные, кроме [$document_root](https://angie.software//angie/docs/configuration/modules/http/index.md#v-document-root) и [$realpath_root](https://angie.software//angie/docs/configuration/modules/http/index.md#v-realpath-root).
Путь к файлу формируется путем простого добавления URI к значению директивы root. Если же URI необходимо поменять, следует воспользоваться директивой [alias](#adc-alias).
### satisfy
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `satisfy` `all` | `any`; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `satisfy all;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает доступ, если его разрешают все (`all`) или хотя бы один (`any`) из модулей [Access](https://angie.software//angie/docs/configuration/modules/http/http_access.md#http-access), [Auth Basic](https://angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic) или [Auth Request](https://angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request).
```nginx
location / {
satisfy any;
allow 192.168.1.0/32;
deny all;
auth_basic "closed site";
auth_basic_user_file conf/htpasswd;
}
```
### send_lowat
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `send_lowat` размер; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | `send_lowat 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
При установке этой директивы в ненулевое значение Angie будет пытаться
минимизировать число операций отправки на клиентских сокетах либо при помощи
флага `NOTE_LOWAT` метода [kqueue](https://angie.software//angie/docs/configuration/processing.md#kqueue), либо при помощи
параметра сокета `SO_SNDLOWAT`. В обоих случаях будет использован
указанный размер.
### send_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `send_timeout` время; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | `send_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при передаче ответа клиенту. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями записи. Если по истечении этого времени клиент ничего не примет, соединение будет закрыто.
### sendfile
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `sendfile` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `sendfile off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Разрешает или запрещает использовать `sendfile()`.
Возможно использование [aio](#adc-aio) для подгрузки данных для `sendfile()`:
```nginx
location /video/ {
sendfile on;
tcp_nopush on;
aio on;
}
```
В такой конфигурации функция `sendfile()` вызывается с флагом `SF_NODISKIO`, в результате чего она не блокируется на диске, а сообщает об отсутствии данных в памяти. После этого Angie инициирует асинхронную подгрузку данных, читая один байт. При этом ядро FreeBSD подгружает в память первые 128K байт файла, однако при последующих чтениях файл подгружается частями только по 16K. Изменить это можно с помощью директивы [read_ahead](#adc-read-ahead).
### sendfile_max_chunk
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `sendfile_max_chunk` размер; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `sendfile_max_chunk 2m;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает объем данных, который может передан за один вызов `sendfile()`. Без этого ограничения одно быстрое соединение может целиком захватить рабочий процесс.
### server
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `server` { ... } |
|------------------------------------------------------------------------------------------|--------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает конфигурацию для виртуального сервера. Четкого разделения виртуальных серверов на IP-based (на основании IP-адреса) и name-based (на основании поля "Host" заголовка запроса) нет. Вместо этого директивами [listen](#adc-listen) описываются все адреса и порты, на которых нужно принимать соединения для этого сервера, а в директиве [server_name](#adc-server-name) указываются все имена серверов.
Подробнее: [Как обрабатываются запросы](https://angie.software//angie/docs/configuration/processing.md#request-processing)
### server_name
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `server_name` имя ...; |
|------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию | `server_name ""`; |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server |
Задает имена виртуального сервера, например:
```nginx
server {
server_name example.com www.example.com;
}
```
Первое имя становится основным именем сервера.
В именах серверов можно использовать звездочку ("\*") для замены первой или последней части имени:
```nginx
server {
server_name example.com *.example.com www.example.*;
}
```
Такие имена называются именами с маской.
Два первых вышеприведенных имени можно объединить в одно:
```nginx
server {
server_name .example.com;
}
```
В качестве имени сервера можно также использовать регулярное выражение, указав перед ним тильду ("~"):
```nginx
server {
server_name ~^www\d+\.example\.com$ www.example.com;
}
```
Регулярное выражение может содержать группы захвата, которые могут затем использоваться в других директивах:
```nginx
server {
server_name ~^(www\.)?(.+)$;
location / {
root /sites/$2;
}
}
server {
server_name _;
location / {
root /sites/default;
}
}
```
Именованные группы захвата в регулярном выражении создают переменные,
которые могут затем использоваться в других директивах:
```nginx
server {
server_name ~^(www\.)?(?.+)$;
location / {
root /sites/$domain;
}
}
server {
server_name _;
location / {
root /sites/default;
}
}
```
#### NOTE
Если параметр директивы задан как [$hostname](https://angie.software//angie/docs/configuration/modules/http/index.md#v-hostname),
используется имя хоста веб-сервера.
Можно также указать пустое имя сервера (`""`):
```nginx
server {
server_name www.example.com "";
}
```
При поиске виртуального сервера по имени,
которому соответствует несколько указанных вариантов
(например, одновременно подходят и имя с маской, и регулярное выражение),
будет выбран первый подходящий вариант в следующем порядке приоритета:
- точное имя;
- самое длинное имя с маской в начале, например `*.example.com`;
- самое длинное имя с маской в конце, например `mail.*`;
- первое подходящее регулярное выражение (в порядке следования в конфигурации),
в том числе пустое имя.
#### WARNING
Чтобы использовать `server_name` с TLS,
необходима терминация TLS-соединения.
Эта директива сопоставляется с `Host` в HTTP-запросе,
поэтому рукопожатие должно быть закончено, а соединение расшифровано.
### server_name_in_redirect
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `server_name_in_redirect` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| По умолчанию | `server_name_in_redirect off`; |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает использовать в [абсолютных](https://angie.software//angie/docs/configuration/modules/http/index.md#absolute-redirect) перенаправлениях, выдаваемых Angie, основное имя сервера, задаваемое директивой [server_name](#adc-server-name).
| `on` | используется основное имя сервера, задаваемое директивой [server_name](#adc-server-name) |
|--------|------------------------------------------------------------------------------------------------------------------------|
| `off` | используется имя, указанное в поле "Host" заголовка запроса. Если же этого поля нет, то используется IP-адрес сервера. |
Использование в перенаправлениях порта управляется директивой [port_in_redirect](#adc-port-in-redirect).
### server_names_hash_bucket_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `server_names_hash_bucket_size` размер; |
|------------------------------------------------------------------------------------------|----------------------------------------------------|
| По умолчанию | `server_names_hash_bucket_size 32` | `64` | `128;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает размер корзины в хэш-таблицах имен серверов. Значение по умолчанию зависит от размера строки кэша процессора. Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
### server_names_hash_max_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `server_names_hash_max_size` размер; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `server_names_hash_max_size 512`; |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает максимальный размер хэш-таблиц имен серверов. Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
### server_tokens
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `server_tokens` `on` | `off` | `build` | строка; |
|------------------------------------------------------------------------------------------|----------------------------------------------------|
| По умолчанию | `server_tokens on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает указывать версию Angie
на страницах ошибок и в поле заголовка ответа `Server`.
Если указан параметр `build`,
то вместе с версией будет также указано имя сборки,
заданное соответствующим параметром скрипта.
Директива может быть задана строкой,
которая может также содержать переменные.
Тогда на страницах ошибок и в поле заголовка ответа `Server`
вместо имени сервера, версии и имени сборки
будет указываться значение этой строки с подставленными переменными.
Пустая строка запрещает выдачу поля `Server`.
### status_zone
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `status_zone` `off` | зона | ключ `zone=`зона[:число]; |
|------------------------------------------------------------------------------------------|----------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location, if в location |
Выделяет зону разделяемой памяти для сбора метрик
[/status/http/location_zones/<зона>](https://angie.software//adc/docs/load_balancer/reference/http/http_api.md#adc-api-status-http-location-zones) и [/status/http/server_zones/<зона>](https://angie.software//adc/docs/load_balancer/reference/http/http_api.md#adc-api-status-http-server-zones).
Несколько контекстов `server`
могут совместно использовать одну и ту же зону для сбора данных;
особое значение `off`
выключает сбор данных во вложенных блоках `location`.
Синтаксис с одним значением зоны
объединяет все метрики для текущего контекста в одну зону разделяемой памяти:
```nginx
server {
listen 80;
server_name *.example.com;
status_zone single;
# ...
}
```
Альтернативный синтаксис позволяет задавать следующие параметры:
| ключ | Строка с переменными, значение которой определяет группировку запросов в
зоне. Все запросы, дающие одинаковые значения после подстановки,
объединяются в одну группу. Если подстановка возвращает пустое значение,
метрики не обновляются. |
|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| зона | Имя зоны разделяемой памяти. |
| число (необязательный) | Максимальное количество отдельных групп для сбора метрик.
Если новые значения ключа превышают этот лимит, они объединяются в группу `zone`.
Значение по умолчанию — 1. |
В следующем примере все запросы с одинаковым значением `$host`
группируются в `host_zone`. Метрики собираются отдельно для каждого
уникального значения `$host` до тех пор, пока количество групп метрик не
достигнет 10. После этого любые новые значения `$host` будут добавляться в
группу `host_zone`:
```nginx
server {
listen 80;
server_name *.example.com;
status_zone $host zone=host_zone:10;
location / {
proxy_pass http://example.com;
}
}
```
Результирующие метрики разделяются по отдельным хостам в выводе API.
#### NOTE
Эти метрики собираются, только если задан `status_zone`. Без него
сервер или location не отображается в [/status/http/server_zones/<зона>](https://angie.software//adc/docs/load_balancer/reference/http/http_api.md#adc-api-status-http-server-zones),
[/status/http/location_zones/<зона>](https://angie.software//adc/docs/load_balancer/reference/http/http_api.md#adc-api-status-http-location-zones),
[виджете «HTTP Zones»](https://angie.software//angie/docs/configuration/monitoring.md#http-zones-widget)
и в выводе [Prometheus](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus),
и предупреждение при этом не выводится.
См. [пример конфигурации](https://angie.software//angie/docs/configuration/modules/http/http_api.md#example-configuration).
### subrequest_output_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `subrequest_output_buffer_size` размер; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `subrequest_output_buffer_size 4k` | `8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает размер буфера, используемого для хранения тела ответа подзапроса. По умолчанию размер одного буфера равен размеру страницы памяти. В зависимости от платформы это или `4K`, или `8K`, однако его можно сделать меньше.
#### NOTE
Директива применима только для подзапросов, тело ответа которых сохраняется в памяти. Например, подобные подзапросы создаются при помощи [SSI](https://angie.software//angie/docs/configuration/modules/http/http_ssi.md#ssi-include-set).
### tcp_nodelay
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `tcp_nodelay` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `tcp_nodelay on`; |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает использование параметра `TCP_NODELAY`. Параметр включается при переходе соединения в состояние keep-alive. Также, он включается на SSL-соединениях, при небуферизованном проксировании и при [проксировании WebSocket](https://angie.software//angie/docs/configuration/processing.md#websocket-proxy).
### tcp_nopush
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `tcp_nopush` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `tcp_nopush off`; |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает использование параметра сокета `TCP_NOPUSH` во
FreeBSD или `TCP_CORK` в Linux. Параметр включается только при
использовании [sendfile](#adc-sendfile). Включение параметра позволяет:
* передавать заголовок ответа и начало файла в одном пакете в Linux и во FreeBSD 4.\*;
* передавать файл полными пакетами.
### try_files
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `try_files` файл ... uri;
`try_files` файл ... =код; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location |
Проверяет существование файлов в заданном порядке и использует для обработки
запроса первый найденный файл, причем обработка делается в контексте этого же
`location`'а. Путь к файлу строится из параметра файл в соответствии с
директивами [root](#adc-root) и [alias](#adc-alias). С помощью косой черты в
конце имени можно проверить существование каталога, например, `$uri/`. В
случае, если ни один файл не найден, производится внутреннее перенаправление на
uri, заданный последним параметром.
Например:
```nginx
location /images/ {
try_files $uri /images/default.gif;
}
location = /images/default.gif {
expires 30s;
}
```
Последний параметр может быть URI для внутреннего перенаправления,
ссылкой на именованный `location` (например, `@drupal`)
или кодом ответа в форме `=код` (например, `=404`):
```nginx
location / {
try_files $uri $uri/index.html $uri.html =404;
}
```
Следует помнить, что чрезмерное использование директивы `try_files`
увеличивает число системных вызовов,
что может негативно сказаться на производительности.
Так, не следует использовать `try_files` для формирования поведения,
фактически дублирующего поведение по умолчанию, например:
```nginx
location /bad_pattern {
# try_files $uri $uri/ =404; # не рекомендуется!
}
```
Также не следует использовать `try_files`
исключительно для перенаправления при отсутствии файла.
Дело в том, что директива `try_files` имеет две особенности:
- Во-первых, она проверяет существование каждого файла,
что увеличивает нагрузку на систему.
- Во-вторых, любые ошибки открытия файла (например, `too many open files`,
ошибки прав доступа) также считаются отсутствием файла и вызывают переход к
запасному обработчику, что может привести к подмене ошибок 5xx успешными
ответами и некорректному кэшированию.
Так, на практике можно встретить следующую проблемную конструкцию:
```nginx
location / {
try_files $uri $uri/ @drupal; # не рекомендуется!
}
```
Ее проблема в том, что единственная цель здесь — перенаправление.
Использование `try_files` приводит к перечисленным выше недостаткам,
но не дает никаких преимуществ,
поскольку проверка существования файлов не нужна.
Правильное решение — использовать директиву [error_page](https://angie.software//angie/docs/configuration/modules/http/index.md#error-page),
которая лишена этих недостатков:
```nginx
error_page 404 = @drupal;
log_not_found off;
```
Напротив, в следующем примере:
```nginx
location ~ \.php$ {
try_files $uri @drupal;
fastcgi_pass ...;
fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
# ...
}
```
Директива `try_files` проверяет существование PHP-файла,
прежде чем передать запрос настроенному в том же блоке FastCGI-серверу;
здесь использование `try_files` оправдано.
### Пример использования при проксировании Mongrel:
```nginx
location / {
try_files /system/maintenance.html
$uri $uri/index.html $uri.html
@mongrel;
}
location @mongrel {
proxy_pass http://mongrel;
}
```
### Пример использования вместе с Drupal/FastCGI:
```nginx
location / {
error_page 404 = @drupal;
}
location ~ \.php$ {
try_files $uri @drupal;
fastcgi_pass ...;
fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
fastcgi_param SCRIPT_NAME $fastcgi_script_name;
fastcgi_param QUERY_STRING $args;
# ... прочие fastcgi_param
}
location @drupal {
fastcgi_pass ...;
fastcgi_param SCRIPT_FILENAME /path/to/index.php;
fastcgi_param SCRIPT_NAME /index.php;
fastcgi_param QUERY_STRING q=$uri&$args;
# ... прочие fastcgi_param
}
```
### Пример использования вместе с Wordpress и Joomla:
```nginx
location / {
error_page 404 = @wordpress;
}
location ~ \.php$ {
try_files $uri @wordpress;
fastcgi_pass ...;
fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
# ... прочие fastcgi_param
}
location @wordpress {
fastcgi_pass ...;
fastcgi_param SCRIPT_FILENAME /path/to/index.php;
# ... прочие fastcgi_param
}
```
### types
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `types` { ... } |
|------------------------------------------------------------------------------------------|------------------------------------------------------------|
| По умолчанию | `types *text/html html; image/gif gif; image/jpeg jpg;* ` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает соответствие расширений имен файлов и MIME-типов ответов. Расширения нечувствительны к регистру символов. Одному MIME-типу может соответствовать несколько расширений, например:
```nginx
types {
application/octet-stream bin exe dll;
application/octet-stream deb;
application/octet-stream dmg;
}
```
Достаточно полная таблица соответствий входит в дистрибутив Angie и находится в файле `conf/mime.types`.
Для того чтобы для определенного `location`'а для всех ответов выдавался MIME-тип "application/octet-stream", можно использовать следующее:
```nginx
location /download/ {
types { }
default_type application/octet-stream;
}
```
### types_hash_bucket_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `types_hash_bucket_size` размер; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `types_hash_bucket_size 64;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает размер корзины в хэш-таблицах типов. Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
### types_hash_max_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `types_hash_max_size` размер; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `types_hash_max_size 1024;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает максимальный размер хэш-таблиц типов. Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
### underscores_in_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `underscores_in_headers` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `underscores_in_headers off`; |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает или запрещает использование символов подчеркивания в полях заголовка запроса клиента. Если использование символов подчеркивания запрещено, поля заголовка запроса, в именах которых есть подчеркивания, помечаются как недопустимые и подпадают под действие директивы [ignore_invalid_headers](#adc-ignore-invalid-headers).
Если директива указана на уровне [server](#adc-server), то может использоваться значение из сервера по умолчанию.
### variables_hash_bucket_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `variables_hash_bucket_size` размер; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `variables_hash_bucket_size 64;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает размер корзины в хэш-таблице переменных. Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
### variables_hash_max_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `variables_hash_max_size` размер; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `variables_hash_max_size 2048;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает максимальный размер хэш-таблиц переменных. Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
## Встроенные переменные
Модуль `http_core` поддерживает встроенные переменные, имена которых совпадают с именами переменных веб-сервера Apache. Прежде всего, это переменные, представляющие из себя поля заголовка запроса клиента, такие как `$http_user_agent`, `$http_cookie` и тому подобное. Кроме того, есть и другие переменные:
### `$angie_version`
версия Angie
### `$arg_<имя>`
аргумент имя в строке запроса
### `$args`
аргументы в строке запроса
### `$binary_remote_addr`
адрес клиента в бинарном виде, длина значения всегда 4 байта для IPv4-адресов или 16 байт для IPv6-адресов
### `$body_bytes_sent`
число байт, переданное клиенту, без учета заголовка ответа; переменная совместима с параметром "%B" модуля Apache `mod_log_config`
### `$bytes_sent`
число байт, переданных клиенту
### `$connection`
порядковый номер соединения
### `$connection_requests`
текущее число запросов в соединении
### `$connection_time`
время соединения в секундах с точностью до миллисекунд
### `$content_length`
поле `Content-Length` заголовка запроса
### `$content_type`
поле `Content-Type` заголовка запроса
### `$cookie_<имя>`
cookie с указанным именем
### `$document_root`
значение директивы [root](#adc-root) или [alias](#adc-alias) для текущего запроса
### `$document_uri`
то же, что и [$uri](https://angie.software//angie/docs/configuration/modules/http/index.md#v-uri)
### `$host`
в порядке приоритета: имя хоста из строки запроса, или имя хоста из поля "Host" заголовка запроса, или имя сервера, соответствующего запросу
### `$hostname`
имя хоста
### `$http_<имя>`
произвольное поле заголовка запроса; последняя часть имени переменной соответствует имени поля, приведенному к нижнему регистру, с заменой символов тире на символы подчеркивания
### `$https`
`on` если соединение работает в режиме SSL, либо пустая строка
### `$is_args`
`?`, если в строке запроса есть аргументы, и пустая строка, если их нет
### `$is_request_port`
`:`, если значение [$request_port](https://angie.software//angie/docs/configuration/modules/http/index.md#v-request-port) непустое, либо пустая строка
### `$limit_rate`
установка этой переменной позволяет ограничивать скорость передачи ответа, см. [limit_rate](#adc-limit-rate)
### `$msec`
текущее время в секундах с точностью до миллисекунд
### `$nginx_version`
версия nginx
### `$pid`
номер (PID) рабочего процесса
### `$pipe`
`p` если запрос был pipelined, иначе `.`
### `$proxy_protocol_addr`
Адрес клиента, полученный из заголовка протокола PROXY.
Протокол PROXY должен быть предварительно включен при помощи установки параметра `proxy_protocol` в директиве [listen](#adc-listen).
### `$proxy_protocol_port`
Порт клиента, полученный из заголовка протокола PROXY.
Протокол PROXY должен быть предварительно включен при помощи установки параметра `proxy_protocol` в директиве [listen](#adc-listen).
### `$proxy_protocol_server_addr`
Адрес сервера, полученный из заголовка протокола PROXY.
Протокол PROXY должен быть предварительно включен при помощи установки параметра `proxy_protocol` в директиве [listen](#adc-listen).
### `$proxy_protocol_server_port`
Порт сервера, полученный из заголовка протокола PROXY.
Протокол PROXY должен быть предварительно включен при помощи установки параметра `proxy_protocol` в директиве [listen](#adc-listen).
### `$proxy_protocol_tlv_<имя>`
TLV, полученный из заголовка протокола PROXY. Имя может быть именем типа TLV или его числовым значением. В последнем случае значение задается в шестнадцатеричном виде и должно начинаться с `0x`:
```none
$proxy_protocol_tlv_alpn
$proxy_protocol_tlv_0x01
```
SSL TLV могут также быть доступны как по имени типа TLV, так и по его числовому значению, оба должны начинаться с `ssl_`:
```none
$proxy_protocol_tlv_ssl_version
$proxy_protocol_tlv_ssl_0x21
```
Поддерживаются следующие имена типов TLV:
* `alpn (0x01)` - протокол более высокого уровня, используемый поверх соединения
* `authority (0x02)` - значение имени хоста, передаваемое клиентом
* `unique_id (0x05)` - уникальный идентификатор соединения
* `netns (0x30)` - имя пространства имен
* `ssl (0x20)` - структура SSL TLV в бинарном виде
Поддерживаются следующие имена типов SSL TLV:
* `ssl_version (0x21)` - версия SSL, используемая в клиентском соединении
* `ssl_cn (0x22)` - Common Name сертификата
* `ssl_cipher (0x23)` - имя используемого шифра
* `ssl_sig_alg (0x24)` - алгоритм, используемый для подписи сертификата
* `ssl_key_alg (0x25)` - алгоритм публичного ключа
Также поддерживается следующее специальное имя типа SSL TLV:
* `ssl_verify` - результат проверки клиентского сертификата: `0`, если клиент предоставил сертификат и он был успешно верифицирован, либо ненулевое значение
Протокол PROXY должен быть предварительно включен при помощи установки параметра `proxy_protocol` в директиве [listen](#adc-listen).
### `$query_string`
то же, что и [$args](https://angie.software//angie/docs/configuration/modules/http/index.md#v-args)
### `$realpath_root`
абсолютный путь, соответствующий значению директивы [root](#adc-root) или [alias](#adc-alias) для текущего запроса, в котором все символические ссылки преобразованы в реальные пути
### `$remote_addr`
адрес клиента
### `$remote_port`
порт клиента
### `$remote_user`
имя пользователя, использованное в Basic аутентификации
### `$request`
первоначальная строка запроса целиком
### `$request_body`
Тело запроса.
Значение переменной *появляется* в [location](#adc-location)'ах, обрабатываемых директивами [proxy_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-pass), [fastcgi_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_fastcgi.md#adc-fastcgi-pass), [uwsgi_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_uwsgi.md#adc-uwsgi-pass) и [scgi_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_scgi.md#adc-scgi-pass), когда тело было прочитано в [буфер в памяти](https://angie.software//angie/docs/configuration/modules/http/index.md#client-body-buffer-size).
### `$request_body_file`
Имя временного файла, в котором хранится тело запроса.
По завершении обработки файл необходимо удалить. Для того чтобы тело запроса всегда записывалось в файл, следует включить [client_body_in_file_only](#adc-client-body-in-file-only). При передаче имени временного файла в проксированном запросе или в запросе к FastCGI/uwsgi/SCGI-серверу следует запретить передачу самого тела директивами [proxy_pass_request_body off](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass-request-body), [fastcgi_pass_request_body off](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass-request-body), [uwsgi_pass_request_body off](https://angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass-request-body) или [scgi_pass_request_body off](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass-request-body) соответственно.
### `$request_completion`
`OK`, если запрос завершился, либо пустая строка
### `$request_filename`
путь к файлу для текущего запроса, формируемый из директив [root](#adc-root) или [alias](#adc-alias) и URI запроса
### `$request_id`
уникальный идентификатор запроса, сформированный из 16 случайных байт, в шестнадцатеричном виде
### `$request_length`
длина запроса (включая строку запроса, заголовок и тело запроса)
### `$request_method`
метод запроса, обычно `GET` или `POST`
### `$request_port`
в порядке приоритета: номер порта из компонента authority URI, или номер порта из поля заголовка запроса `Host`
### `$request_time`
время обработки запроса в секундах с точностью до миллисекунд; время, прошедшее с момента чтения первых байт от клиента
### `$request_uri`
первоначальный URI запроса целиком (с аргументами), не изменяется в процессе обработки запроса; см. [$uri](https://angie.software//angie/docs/configuration/modules/http/index.md#v-uri) — текущий URI с учётом всех преобразований
### `$scheme`
схема запроса, "http" или "https"
### `$sent_body`
тело ответа подзапроса или внешнего запроса, если оно сохранено в памяти;
иначе пустая строка
### `$sent_http_<имя>`
произвольное поле заголовка ответа; последняя часть имени переменной соответствует имени поля, приведенному к нижнему регистру, с заменой символов тире на символы подчеркивания
### `$sent_trailer_<имя>`
произвольное поле, отправленное в конце ответа; последняя часть имени переменной соответствует имени поля, приведенному к нижнему регистру, с заменой символов тире на символы подчеркивания
### `$server_addr`
Адрес сервера, принявшего запрос.
Получение значения этой переменной обычно требует одного системного вызова. Чтобы избежать системного вызова, в директивах [listen](#adc-listen) следует указывать адреса и использовать параметр `bind`.
### `$server_name`
имя сервера, принявшего запрос
### `$server_port`
порт сервера, принявшего запрос
### `$server_protocol`
протокол запроса, обычно "HTTP/1.0", "HTTP/1.1" или "HTTP/2.0"
### `$status`
статус ответа
### `$time_iso8601`
локальное время в формате по стандарту ISO 8601
### `$time_local`
локальное время в Common Log Format
### `$tcpinfo_rtt, $tcpinfo_rttvar, $tcpinfo_snd_cwnd, $tcpinfo_rcv_space`
информация о клиентском TCP-соединении; доступна на системах, поддерживающих параметр сокета `TCP_INFO`
### `$uri`
Текущий URI запроса в [нормализованном](https://angie.software//angie/docs/configuration/modules/http/index.md#location) виде.
Значение `$uri` может изменяться в процессе обработки запроса, например, при перезаписи с помощью [rewrite](https://angie.software//adc/docs/load_balancer/reference/http/http_rewrite.md#adc-rewrite), при внутренних перенаправлениях или при использовании индексных файлов.
# https://angie.software/adc/docs/load_balancer/reference/http/http_access.md
# Access
Модуль управляет доступом к ресурсам сервера на основе IP-адресов клиентов или
сетей. Он позволяет разрешать или блокировать доступ для определенных
IP-адресов, IP-диапазонов или UNIX-сокетов, чтобы повысить безопасность,
ограничивая доступ к важным разделам веб-сайта или приложения.
Доступ также можно ограничить с помощью пароля, используя модуль [Auth
Basic](https://angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic), или на основе результата подзапроса, используя модуль
[Auth Request](https://angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request). Чтобы одновременно применять
ограничения по адресу и паролю, используйте директиву [satisfy](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-satisfy).
## Пример конфигурации
```nginx
location / {
deny 192.168.1.1;
allow 192.168.1.0/24;
allow 10.1.1.0/16;
allow 2001:0db8::/32;
deny all;
}
```
Правила обрабатываются последовательно до первого совпадения. В этом примере
доступ разрешен только для IPv4-сетей `10.1.1.0/16` и
`192.168.1.0/24`, за исключением отдельного адреса `192.168.1.1`, и
для IPv6-сети `2001:0db8::/32`. Когда правил много,
предпочтительно использовать переменные из модуля [Geo](https://angie.software//angie/docs/configuration/modules/http/http_geo.md#http-geo).
## Директивы
### allow
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `allow` адрес | CIDR | `unix:` | `all`; |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, limit_except |
Разрешает доступ для указанной сети или адреса.
Специальное значение `all` означает все IP-адреса клиентов.
Специальное значение `unix:` разрешает доступ для любых UNIX-сокетов.
### deny
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `deny` адрес | CIDR | `unix:` | `all`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, limit_except |
Запрещает доступ для указанной сети или адреса.
Специальное значение `all` означает все IP-адреса клиентов.
Специальное значение `unix:` запрещает доступ для любых UNIX-сокетов.
# https://angie.software/adc/docs/load_balancer/reference/http/http_acme.md
# ACME
Обеспечивает автоматическое получение сертификатов с использованием [протокола
ACME](https://datatracker.ietf.org/doc/html/rfc8555).
## Пример конфигурации
В этом примере ACME-клиент с именем `example` автоматически получает и
обновляет сертификат для `example.com` и `www.example.com`,
используя HTTP-проверку по умолчанию:
```nginx
http {
resolver 127.0.0.53; # требуется для директивы 'acme_client'
acme_client example https://acme-v02.api.letsencrypt.org/directory;
server {
listen 80; # Необязательно, если нет сервера,
# слушающего порт HTTP‑проверки
# (см. директиву 'acme_http_port')
listen 443 ssl;
server_name example.com www.example.com;
acme example;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
}
}
```
Другие методы проверки (DNS, ALPN, с помощью хуков) и подробные инструкции
по настройке см. в разделе [Настройка ACME](https://angie.software//adc/docs/load_balancer/reference/acme.md#adc-acme-config).
## Директивы
### acme
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `acme` имя; |
|------------------------------------------------------------------------------------------|---------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server |
Указывает [клиент ACME](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client), который получает сертификат
для доменов этого блока [server](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-server).
Единый сертификат охватывает все домены, указанные в директивах
[server_name](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-server-name) всех блоков [server](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-server),
которые ссылаются на клиент с именем имя;
если изменится конфигурация `server_name`,
сертификат обновляется для учета изменений.
При каждом запуске Angie для всех доменов,
у которых отсутствует действующий сертификат, запрашиваются новые сертификаты.
Возможные причины включают истечение срока действия сертификатов,
отсутствие файлов или невозможность прочитать их,
а также изменения в настройках сертификатов.
#### NOTE
Эта директива определяет только то, какие доменные имена
включаются в запросы сертификатов;
она не влияет на то, где можно использовать сертификат.
Любой блок `server` может ссылаться на сертификат
через переменную [$acme_cert_<имя>](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-name),
независимо от того, содержит ли блок директиву `acme`.
Удаление `acme` из блока `server`
просто исключает значения [server_name](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-server-name) этого блока
из последующих запросов сертификатов,
но не запрещает блоку использовать сертификат.
#### NOTE
Сейчас домены, заданные через регулярные выражения,
не поддерживаются и будут пропускаться.
Домены со звездочкой поддерживаются только в режиме `challenge=dns`
в `acme_client`.
Эта директива может быть указана несколько раз
для загрузки сертификатов разных типов, например RSA и ECDSA:
```nginx
server {
listen 443 ssl;
server_name example.com www.example.com;
ssl_certificate $acme_cert_rsa;
ssl_certificate_key $acme_cert_key_rsa;
ssl_certificate $acme_cert_ecdsa;
ssl_certificate_key $acme_cert_key_ecdsa;
acme rsa;
acme ecdsa;
}
```
### acme_client
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_client` имя uri [`enabled=``on` | `off`] [`key_type=`тип] [`key_bits=`число] [`email=`email] [`max_cert_size=`число] [`max_key_auth_size=`размер] [`renew_before_expiry=`время] [`renew_on_load`] [`retry_after_error=`off|время] [`challenge=``dns` | `http` | `alpn`] [`account_key=`файл]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Определяет клиент ACME с глобально уникальным именем.
Оно должно быть допустимым для каталога,
представляет собой строку с переменными
и будет использоваться без учета регистра.
Каждый клиент управляет одним сертификатом; чтобы получить отдельные
сертификаты, настройте несколько блоков `acme_client` (см.
[Отдельные сертификаты для разных доменов](https://angie.software//adc/docs/load_balancer/reference/acme.md#adc-acme-config-multiple-clients)).
Вторым обязательным параметром является uri каталога ACME.
Например, URI каталога Let's Encrypt ACME [указан](https://letsencrypt.org/getting-started/)
как
[https://acme-v02.api.letsencrypt.org/directory](https://acme-v02.api.letsencrypt.org/directory).
#### NOTE
Модуль ACME добавляет в контекст [client](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-client)
именованный `location @acme`,
который можно использовать для настройки запросов к каталогу ACME;
По умолчанию в этом `location`
задана директива [proxy_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-pass) с uri каталога,
к которой можно добавить другие настройки из модуля [Proxy](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-http-proxy).
Чтобы директива работала,
в том же контексте должен быть настроен [resolver](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-resolver).
#### NOTE
Для тестирования
удостоверяющие центры обычно предоставляют отдельные тестовые среды.
Например, [среда тестирования Let's Encrypt](https://letsencrypt.org/docs/staging-environment/)
—
[https://acme-staging-v02.api.letsencrypt.org/directory](https://acme-staging-v02.api.letsencrypt.org/directory).
| `enabled` | Включает или отключает обновление сертификатов для клиента;
это полезно, например, для временной приостановки
без удаления клиента из конфигурации.
По умолчанию: `on`. |
|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `key_type` | Тип алгоритма закрытого ключа для сертификата.
Допустимые значения: `rsa`, `ecdsa`.
По умолчанию: `ecdsa`. |
| `key_bits` | Количество битов в ключе сертификата.
По умолчанию: 256 для `ecdsa`, 2048 для `rsa`. |
| `email` | Необязательный адрес электронной почты для обратной связи;
используется при создании учетной записи на сервере CA. |
| `max_cert_size` | Задает максимальный допустимый размер файла нового сертификата в байтах,
чтобы зарезервировать место для нового сертификата в разделяемой памяти;
чем больше число доменов, для которых запрашивается сертификат,
тем больше требуется места.
Этот параметр не ограничивает размер ответа ACME‑сервера;
для этого используется [acme_max_response_size](#adc-acme-max-response-size).
Если параметр не задан, Angie вычисляет приблизительный размер
на основе списка доменов и использует его при выделении
разделяемой памяти.
Если в момент запуска сертификат уже существует, но его размер
превышает значение `max_cert_size`, значение
`max_cert_size` динамически увеличивается до размера
существующего файла сертификата.
Если размер сертификата, полученного при обновлении,
превышает `max_cert_size`,
процесс обновления завершится с ошибкой.
По умолчанию: вычисляется автоматически. |
| `max_key_auth_size` | Ограничивает размер строки авторизации ключа,
которую Angie хранит в разделяемой памяти для ACME-проверки.
Если ACME-сервер возвращает строку авторизации ключа
большего размера, запрос завершается ошибкой
с рекомендацией увеличить `max_key_auth_size`.
Хотя параметр задается в строке `acme_client`,
это единая настройка, общая для всех клиентов
в блоке `http`.
По умолчанию: `2k`. |
| `renew_before_expiry` | [Время](https://angie.software//angie/docs/configuration/configfile.md#syntax) до истечения срока действия сертификата,
когда должно начаться его обновление.
По умолчанию: `30d`. |
| `renew_on_load` | Указывает, что сертификат следует принудительно обновлять
при каждой загрузке конфигурации. |
| `retry_after_error` | [Время](https://angie.software//angie/docs/configuration/configfile.md#syntax) до повторной попытки,
если получить сертификат не удалось.
Если задано значение `off`,
клиент не будет снова пытаться получить сертификат после ошибки.
По умолчанию: `2h`. |
| `challenge` | Задает тип верификации для ACME-клиента.
Допустимые значения: `dns`, `http`, `alpn`.
Значение `alpn` включает проверку [TLS-ALPN-01](https://datatracker.ietf.org/doc/rfc8737/) и требует,
чтобы Angie был собран с OpenSSL с поддержкой ALPN
(не поддерживается сборками с BoringSSL и AWS-LC).
По умолчанию: `http`. |
| `account_key` | Указывает полный путь к файлу, содержащему ключ в формате PEM.
Это удобно, если вы хотите использовать существующий ключ аккаунта
вместо автоматической генерации,
или если вам нужно использовать один ключ для нескольких ACME-клиентов.
Поддерживаемые типы ключей:
- RSA-ключи с длиной, кратной 8, в диапазоне от 2048 до 8192 бит.
- ECDSA-ключи с длиной 256, 384 или 521 бит.
При указании параметра `account_key` следует убедиться,
что файл ключа действительно существует.
Если файл отсутствует,
Angie попытается создать его по указанному пути.
Следует учитывать, что ключи для ACME-клиентов создаются в том порядке,
в каком соответствующие клиенты упомянуты в конфигурации
в директивах [acme_client](#adc-acme-client), [acme](#adc-acme) или [acme_hook](#adc-acme-hook).
Поэтому, если один клиент должен использовать ключ,
созданный для другого,
этот другой клиент должен стоять в конфигурации раньше.
Кроме того, ключи создаются только для клиентов,
у которых задан параметр `enabled=on`. |
### acme_max_response_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_max_response_size` размер; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `acme_max_response_size 32k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Ограничивает максимальный размер тела ответа ACME‑сервера. Если ответ
превышает это значение, запрос завершится ошибкой. Увеличьте значение,
если появляются ошибки вида `too big subrequest response while sending to client`.
### acme_client_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_client_path` путь; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Переопределяет путь к каталогу для хранения сертификатов и ключей,
заданному при сборке с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`--http-acme-client-path`.
### acme_dns_port
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_dns_port` порт | ip[:порт] | [ip6][:порт]; |
|------------------------------------------------------------------------------------------|----------------------------------------------------|
| Значение по умолчанию | `acme_dns_port 53;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Указывает порт,
который модуль использует для обработки DNS-запросов от ACME-сервера по UDP.
Номер порта должен быть в диапазоне от 1 до 65535.
Также поддерживается указание IP-адреса вместе с опциональным портом.
Могут быть использованы как IPv4-адреса в виде `ip:порт`,
так и IPv6-адреса в виде `[ip6]:порт`:
```nginx
acme_dns_port 8053;
acme_dns_port 127.0.0.1;
acme_dns_port [::1];
```
Чтобы использовать номер порта 1024 или ниже,
Angie должен работать с привилегиями [суперпользователя](https://angie.software//angie/docs/configuration/modules/core.md#user).
### acme_http_port
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_http_port` порт | ip[:порт] | [ip6][:порт]; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------|
| Значение по умолчанию | `acme_http_port 80;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Указывает порт,
который модуль использует для обработки HTTP‑проверок ACME.
Номер порта должен быть в диапазоне от 1 до 65535.
Также поддерживается указание IP-адреса вместе с опциональным портом.
Могут быть использованы как IPv4-адреса в виде `ip:порт`,
так и IPv6-адреса в виде `[ip6]:порт`:
```nginx
acme_http_port 8080;
acme_http_port 127.0.0.1;
acme_http_port [::1];
```
Если ни один сервер не слушает указанный адрес и порт,
модуль создаст отдельный слушающий сокет для HTTP‑проверок.
Чтобы использовать номер порта 1024 или ниже,
Angie должен работать с привилегиями [суперпользователя](https://angie.software//angie/docs/configuration/modules/core.md#user).
### acme_hook
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_hook` имя [uri]; |
|------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Включает проверку домена с помощью хуков
для [ACME-клиента](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client), заданного параметром имя.
Когда для выпуска или обновления сертификата требуется проверка домена,
Angie формирует внутренний запрос
к именованному `location`, в котором размещена эта директива.
Способ обработки запроса полностью зависит
от других директив, заданных в том же `location`,
таких как [fastcgi_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_fastcgi.md#adc-fastcgi-pass), [proxy_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-pass)
или любого другого обработчика запросов.
| имя | Имя [ACME-клиента](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client),
для которого этот хук обрабатывает проверку домена. |
|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| uri | Строка с переменными;
задает URI запроса для вызовов хука.
По умолчанию: `/`. |
Например, следующая конфигурация передает значения [переменных хука](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme-variables)
в приложение FastCGI через URI запроса:
```nginx
acme_hook example uri=/acme_hook/$acme_hook_name?domain=$acme_hook_domain&key=$acme_hook_keyauth;
fastcgi_param REQUEST_URI $request_uri;
fastcgi_pass ...;
```
## Встроенные переменные
### `$acme_cert_<имя>`
Содержимое последнего файла сертификата (если он есть),
полученного клиентом с этим именем.
### `$acme_cert_key_<имя>`
Содержимое файла ключа сертификата,
используемого клиентом с этим именем.
#### NOTE
Файл сертификата доступен,
только если клиент ACME получил хотя бы один сертификат,
а вот файл ключа доступен сразу после запуска.
### `$acme_hook_challenge`
Тип проверки. Возможные значения: `dns`, `http`, `alpn`.
### `$acme_hook_client`
Имя ACME-клиента, инициирующего запрос.
### `$acme_hook_domain`
Проверяемый домен.
Если это wildcard-домен, он будет передан без префикса `*.`.
### `$acme_hook_keyauth`
Строка авторизации:
- При DNS-проверке используется как значение TXT-записи,
имя которой формируется как
`_acme-challenge. + $acme_hook_domain + .`.
- При HTTP-проверке эта строка должна использоваться
в качестве содержимого ответа, запрашиваемого ACME-сервером.
### `$acme_hook_name`
Имя хука. Для разных типов проверки оно может иметь разные значения и смысл:
| Значение | Смысл при DNS-проверке | Смысл при HTTP-проверке |
|--------------------------|--------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|
| `add` (добавление хука) | Необходимо добавить соответствующую TXT-запись в конфигурацию DNS. | Необходимо подготовить ответ на соответствующий HTTP-запрос. |
| `remove` (удаление хука) | Можно удалить TXT-запись из конфигурации DNS. | Данный HTTP-запрос более не актуален;
можно удалить ранее созданный файл со строкой авторизации. |
### `$acme_hook_token`
Токен для проверки.
При HTTP-проверке используется как имя запрашиваемого файла:
`/.well-known/acme-challenge/` + `$acme_hook_token`.
# https://angie.software/adc/docs/load_balancer/reference/http/http_addition.md
# Addition
Фильтр, добавляющий текст до и после ответа.
## Пример конфигурации
```nginx
location / {
add_before_body /before_action;
add_after_body /after_action;
}
```
## Директивы
### add_before_body
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `add_before_body` `uri`; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Добавляет перед телом ответа текст, выдаваемый в результате работы заданного подзапроса. Пустая строка (`""`) в качестве параметра отменяет добавление, унаследованное с предыдущего уровня конфигурации.
### add_after_body
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `add_after_body` `uri`; |
|------------------------------------------------------------------------------------------|---------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Добавляет после тела ответа текст, выдаваемый в результате работы заданного подзапроса. Пустая строка (`""`) в качестве параметра отменяет добавление, унаследованное с предыдущего уровня конфигурации.
### addition_types
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `addition_types` mime-тип ...; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `addition_types text/html;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает добавлять текст в ответах с указанными MIME-типами в дополнение к `text/html`. Специальное значение `*` соответствует любому MIME-типу.
# https://angie.software/adc/docs/load_balancer/reference/http/http_api.md
# API
Модуль `API` реализует HTTP RESTful интерфейс для получения базовой информации
о веб-сервере в формате JSON, а также [статистики](https://angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) по клиентским
соединениям, зонам разделяемой памяти, DNS-запросам, HTTP-запросам, кэшу
HTTP-ответов, сессиям модуля [stream](https://angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) и зонам модулей
[limit_conn http](https://angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#http-limit-conn), [limit_conn stream](https://angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#stream-limit-conn), [limit_req](https://angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req) и [http upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).
#### NOTE
Живой пример вывода API доступен по адресу
[https://console.angie.software/api/](https://console.angie.software/api/).
Интерфейс принимает HTTP-методы `GET` и `HEAD`;
запрос с другим методом вызовет ошибку:
```json
{
"error": "MethodNotAllowed",
"description": "The POST method is not allowed for the requested API element \"/\"."
}
```
В этом интерфейсе есть раздел [динамической конфигурации](#adc-api-config), позволяющий менять настройки без перезагрузки конфигурации или
перезапуска; сейчас доступна конфигурация отдельных серверов в составе
[upstream](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-u-upstream).
## Директивы
### api
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `api` путь; |
|------------------------------------------------------------------------------------------|---------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Включает HTTP RESTful интерфейс в `location`.
Параметр путь является обязательным. Подобно директиве [alias](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-alias), задает путь для замены указанного в `location`, но по дереву API, а не файловой системы.
Если указан в префиксном `location`:
```nginx
location /stats/ {
api /status/http/server_zones/;
}
```
часть URI запроса, совпадающая с префиксом /stats/, будет заменена на путь, указанный в параметре путь: /status/http/server_zones/. К примеру, по запросу /stats/foo/ будет доступен элемент API `/status/http/server_zones/foo/`.
Допускается использование переменных: api /status/$module/server_zones/$name/ и использование внутри regex location:
```nginx
location ~^/api/([^/]+)/(.*)$ {
api /status/http/$1_zones/$2;
}
```
Здесь параметр путь определяет полный путь к элементу API;
так, из запроса к `/api/location/data/` будут выделены переменные:
```console
$1 = "location"
$2 = "data/"
```
И конечный запрос будет иметь вид `/status/http/location_zones/data/`.
#### NOTE
Можно разделить [API динамической конфигурации](#adc-api-config) и неизменяемый [API статуса](#adc-metrics), отражающий
текущее состояние:
```nginx
location /config/ {
api /config/;
}
location /status/ {
api /status/;
}
```
Также параметр путь позволяет управлять доступом к API:
```nginx
location /status/ {
api /status/;
allow 127.0.0.1;
deny all;
}
```
Или же:
```nginx
location /blog/requests/ {
api /status/http/server_zones/blog/requests/;
auth_basic "blog";
auth_basic_user_file conf/htpasswd;
}
```
#### NOTE
Если `api` стоит в `location` с косой чертой в конце префикса
(например, `location /name/`),
и при этом в директиве [auto_redirect](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-auto-redirect) указано `default`,
запросы без косой черты в конце будут перенаправляться (`/name -> /name/`).
### api_config_files
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `api_config_files` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | off |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Включает или отключает добавление объекта `config_files`,
перечисляющего содержимое всех файлов конфигурации Angie,
загруженных сейчас экземпляром сервера,
в состав раздела API [/status/angie/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#status-angie).
Например, при такой конфигурации:
```nginx
location /status/ {
api /status/;
api_config_files on;
}
```
Запрос к `/status/angie/` возвращает приблизительно следующее:
```json
{
"version":"|version|",
"address":"192.168.16.5",
"generation":1,
"load_time":"|sampledateshort|T12:58:39.789Z",
"config_files": {
"/etc/angie/angie.conf": "...",
"/etc/angie/mime.types": "..."
}
}
```
По умолчанию вывод отключен, так как файлы конфигурации могут содержать
особо чувствительные, конфиденциальные сведения.
## Метрики
Angie публикует статистику использования в разделе API `/status/`; открыть
доступ к ней можно, задав соответствующий `location`. Полный доступ:
```nginx
location /status/ {
api /status/;
}
```
Пример частичного доступа, уже приводившийся выше:
```nginx
location /stats/ {
api /status/http/server_zones/;
}
```
### Пример конфигурации
С конфигурацией, включающей `location /status/`, зоны `resolver`, `http` в
`upstream`, `http server`, `location`, `cache`, `limit_conn` в
`http` и `limit_req`:
```nginx
http {
resolver 127.0.0.53 status_zone=resolver_zone;
proxy_cache_path /var/cache/angie/cache keys_zone=cache_zone:2m;
limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m;
limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s;
upstream upstream {
zone upstream 256k;
server backend.example.com service=_example._tcp resolve max_conns=5;
keepalive 4;
}
server {
server_name www.example.com;
listen 443 ssl;
status_zone http_server_zone;
proxy_cache cache_zone;
proxy_cache_valid 200 10m;
access_log /var/log/access.log main;
location / {
root /usr/share/angie/html;
status_zone location_zone;
limit_conn limit_conn_zone 1;
limit_req zone=limit_req_zone burst=5;
}
location /status/ {
api /status/;
allow 127.0.0.1;
deny all;
}
}
}
```
В ответ на запрос `curl https://www.example.com/status/` Angie возвращает:
### дерево JSON
```json
{
"angie": {
"version":"|version|",
"address":"192.168.16.5",
"generation":1,
"load_time":"|sampledateshort|T12:58:39.789Z"
},
"connections": {
"accepted":2257,
"dropped":0,
"active":3,
"idle":1
},
"slabs": {
"cache_zone": {
"pages": {
"used":2,
"free":506
},
"slots": {
"64": {
"used":1,
"free":63,
"reqs":1,
"fails":0
},
"512": {
"used":1,
"free":7,
"reqs":1,
"fails":0
}
}
},
"limit_conn_zone": {
"pages": {
"used":2,
"free":2542
},
"slots": {
"64": {
"used":1,
"free":63,
"reqs":74,
"fails":0
},
"128": {
"used":1,
"free":31,
"reqs":1,
"fails":0
}
}
},
"limit_req_zone": {
"pages": {
"used":2,
"free":2542
},
"slots": {
"64": {
"used":1,
"free":63,
"reqs":1,
"fails":0
},
"128": {
"used":2,
"free":30,
"reqs":3,
"fails":0
}
}
}
},
"http": {
"server_zones": {
"http_server_zone": {
"ssl": {
"handshaked":4174,
"reuses":0,
"timedout":0,
"failed":0
},
"requests": {
"total":4327,
"processing":0,
"discarded":8
},
"responses": {
"200":4305,
"302":12,
"404":4
},
"data": {
"received":733955,
"sent":59207757
}
}
},
"location_zones": {
"location_zone": {
"requests": {
"total":4158,
"discarded":0
},
"responses": {
"200":4157,
"304":1
},
"data": {
"received":538200,
"sent":177606236
}
}
},
"caches": {
"cache_zone": {
"size":0,
"cold":false,
"hit": {
"responses":0,
"bytes":0
},
"stale": {
"responses":0,
"bytes":0
},
"updating": {
"responses":0,
"bytes":0
},
"revalidated": {
"responses":0,
"bytes":0
},
"miss": {
"responses":0,
"bytes":0,
"responses_written":0,
"bytes_written":0
},
"expired": {
"responses":0,
"bytes":0,
"responses_written":0,
"bytes_written":0
},
"bypass": {
"responses":0,
"bytes":0,
"responses_written":0,
"bytes_written":0
}
}
},
"limit_conns": {
"limit_conn_zone": {
"passed":73,
"skipped":0,
"rejected":0,
"exhausted":0
}
},
"limit_reqs": {
"limit_req_zone": {
"passed":54816,
"skipped":0,
"delayed":65,
"rejected":26,
"exhausted":0
}
},
"upstreams": {
"upstream": {
"peers": {
"192.168.16.4:80": {
"server":"backend.example.com",
"service":"_example._tcp",
"backup":false,
"weight":5,
"state":"up",
"selected": {
"current":2,
"total":232
},
"max_conns":5,
"responses": {
"200":222,
"302":12
},
"data": {
"sent":543866,
"received":27349934
},
"health": {
"fails":0,
"unavailable":0,
"downtime":0
},
"sid":""
}
},
"keepalive":2
}
}
},
"resolvers": {
"resolver_zone": {
"queries": {
"name":442,
"srv":2,
"addr":0
},
"responses": {
"success":440,
"timedout":1,
"format_error":0,
"server_failure":1,
"not_found":1,
"unimplemented":0,
"refused":1,
"other":0
}
}
}
}
```
Набор метрик можно запросить по отдельной ветви JSON, построив соответствующий запрос. Например:
```console
$ curl https://www.example.com/status/angie
$ curl https://www.example.com/status/connections
$ curl https://www.example.com/status/slabs
$ curl https://www.example.com/status/slabs/<зона>/slots
$ curl https://www.example.com/status/slabs/<зона>/slots/64
$ curl https://www.example.com/status/http/
$ curl https://www.example.com/status/http/acme_clients
$ curl https://www.example.com/status/http/acme_clients/<клиент>
$ curl https://www.example.com/status/http/metric_zones
$ curl https://www.example.com/status/http/metric_zones/<зона>/metrics
$ curl https://www.example.com/status/http/server_zones
$ curl https://www.example.com/status/http/server_zones/
$ curl https://www.example.com/status/http/server_zones//ssl
```
#### NOTE
По умолчанию модуль использует для дат строки в формате ISO 8601;
чтобы вместо этого использовать целочисленный формат эпохи UNIX,
добавьте параметр `date=epoch` к строке запроса:
```console
$ curl https://www.example.com/status/angie/load_time
"2024-04-01T00:59:59+01:00"
$ curl https://www.example.com/status/angie/load_time?date=epoch
1711929599
```
### Состояние сервера
#### `/status/angie`
```json
{
"version": "|version|",
"build_time": "|sampledateshort|T16:05:43.805Z",
"address": "192.168.16.5",
"generation": 1,
"load_time": "|sampledateshort|T16:15:43.805Z"
"config_files": {
"/etc/angie/angie.conf": "...",
"/etc/angie/mime.types": "..."
}
}
```
| `version` | Строка; версия запущенного сервера Angie |
|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `build` | Строка; сборка, если указана при компиляции |
| `build_time` | Строка; время сборки исполняемого файла Angie
в формате [даты](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-date-format) |
| `address` | Строка; адрес сервера, принявшего запрос к API |
| `generation` | Число; версия (поколение) конфигурации,
отсчитываемая с последнего запуска Angie |
| `load_time` | Строка; время последней перезагрузки конфигурации
в формате [даты](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-date-format);
строковые значения даются с миллисекундным разрешением |
| `config_files` | Объект; его члены — абсолютные имена всех файлов конфигурации Angie,
загруженных сейчас экземпляром сервера,
а их значения — строковые представления содержимого файлов, например:
```json
{
"/etc/angie/angie.conf": "server {\n listen 80;\n # ...\n\n}\n"
}
```
#### WARNING
Объект `config_files` есть в `/status/angie/`,
только если включена директива
[api_config_files](https://angie.software//angie/docs/configuration/modules/http/http_api.md#a-api-config-files). |
#### `/status/angie/license`
```json
{
"path": "/etc/angie/license.pem",
"status": "valid",
"owner": "Example Corp",
"days_left": 30,
"since": "2026-01-01",
"until": "2027-01-01",
"limits": {
"worker_processes": 16,
"worker_connections": 65535
}
}
```
| `path` | Строка; полный путь к файлу лицензии |
|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| `status` | Строка; статус лицензии: `missing`, `invalid`, `valid`,
`grace`, `expired` или `pending` |
| `owner` | Строка; владелец лицензии из subject сертификата |
| `days_left` | Число; дни до смены состояния лицензии. Отрицательное значение означает,
что лицензия истекла, и значение показывает число дней после истечения |
| `since` | Строка; дата начала действия лицензии |
| `until` | Строка; дата окончания действия лицензии |
| `limits` | Объект; лимиты лицензии для текущего экземпляра |
### Соединения
#### `/status/connections`
```json
{
"accepted": 2257,
"dropped": 0,
"active": 3,
"idle": 1
}
```
| `accepted` | Число; суммарное количество принятых клиентских соединений |
|--------------|----------------------------------------------------------------|
| `dropped` | Число; суммарное количество сброшенных клиентских соединений |
| `active` | Число; текущее количество активных клиентских соединений |
| `idle` | Число; текущее количество бездействующих клиентских соединений |
### Зоны разделяемой памяти с распределением slab
#### `/status/slabs/<зона>`
Статистика для зон разделяемой памяти с [распределением
slab](https://ru.wikipedia.org/wiki/Slab), таких как [limit_conn](https://angie.software//angie/docs/configuration/modules/http/http_api.md#limit-conn), [limit_req](https://angie.software//angie/docs/configuration/modules/http/http_api.md#limit-req) и [HTTP cache](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache):
```nginx
limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m;
limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s;
proxy_cache cache_zone;
proxy_cache_valid 200 10m;
```
В указанной таким образом зоне разделяемой памяти
будет собираться следующая статистика:
| `pages` | Объект; статистика по страницам памяти |
|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `used` | Число; текущее количество используемых страниц памяти |
| `free` | Число; текущее количество свободных страниц памяти |
| `slots` | Объект; статистика по слотам памяти, по каждому из размеров. `slots` содержит данные по размеру слота памяти ( `8`, `16`, `32`, и т.д., вплоть до половины размера страницы памяти в байтах) |
| `used` | Число; текущее количество используемых слотов памяти заданного размера |
| `free` | Число; текущее количество свободных слотов памяти заданного размера |
| `reqs` | Число; суммарное количество попыток выделения памяти указанного размера |
| `fails` | Число; количество неудавшихся попыток выделения памяти указанного размера |
Пример:
```json
{
"pages": {
"used": 2,
"free": 506
},
"slots": {
"64": {
"used": 1,
"free": 63,
"reqs": 1,
"fails": 0
}
}
```
### DNS-запросы к резолверу
#### `/status/resolvers/<зона>`
Для сбора статистики в директиве [resolver](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-resolver)
нужно задать параметр `status_zone`
([HTTP](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver-status) или [Stream](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-resolver-status)):
```nginx
resolver 127.0.0.53 status_zone=resolver_zone;
```
В указанной таким образом зоне разделяемой памяти
будет собираться следующая статистика:
| `queries` | Объект; статистика запросов |
|------------------|------------------------------------------------------------------------------------|
| `name` | Число; количество запросов на преобразование имен в адреса
(A- и AAAA-запросы) |
| `srv` | Число; количество запросов на преобразование сервисов в адреса
(SRV запросы) |
| `addr` | Число; количество запросов на преобразование адресов в имена
(PTR-запросы) |
| `responses` | Объект; статистика ответов |
| `success` | Число; количество успешных ответов |
| `timedout` | Число; количество запросов, не дождавшихся ответа |
| `format_error` | Число; количество ответов с кодом 1 (Format Error) |
| `server_failure` | Число; количество ответов с кодом 2 (Server Failure) |
| `not_found` | Число; количество ответов с кодом 3 (Name Error) |
| `unimplemented` | Число; количество ответов с кодом 4 (Not Implemented) |
| `refused` | Число; количество ответов с кодом 5 (Refused) |
| `other` | Число; количество запросов, завершенных с другим ненулевым кодом |
| `sent` | Объект; статистика отправленных DNS-запросов |
| `a` | Число; количество запросов типа A |
| `aaaa` | Число; количество запросов типа AAAA |
| `ptr` | Число; количество запросов типа PTR |
| `srv` | Число; количество запросов типа SRV |
#### NOTE
`queries` и `responses` учитывают каждый запрос на разрешение имён,
который Angie выполняет внутренне, включая ответы из TTL-кэша.
`sent` учитывает пакеты, фактически отправленные на сервер имён;
разница между ними отражает обращения к кэшу.
Коды ответов описаны в [RFC 1035](https://datatracker.ietf.org/doc/html/rfc1035.html), часть [4.1.1](https://datatracker.ietf.org/doc/html/rfc1035.html#section-4.1.1).
Различные типы DNS-записей описаны в [RFC 1035](https://datatracker.ietf.org/doc/html/rfc1035.html),
[RFC 2782](https://datatracker.ietf.org/doc/html/rfc2782.html) и
[RFC 3596](https://datatracker.ietf.org/doc/html/rfc3596.html).
Пример:
```json
{
"queries": {
"name": 442,
"srv": 2,
"addr": 0
},
"responses": {
"success": 440,
"timedout": 1,
"format_error": 0,
"server_failure": 1,
"not_found": 1,
"unimplemented": 0,
"refused": 1,
},
"sent": {
"a": 185,
"aaaa": 245,
"srv": 2,
"ptr": 12
}
}
```
### HTTP server и location
#### `/status/http/server_zones/<зона>`
Для сбора статистики в контексте [server](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-server)
нужно задать директиву [status_zone](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-status-zone):
```nginx
server {
...
status_zone server_zone;
}
```
Для группировки метрик по пользовательскому значению
используйте альтернативный синтаксис.
В этом примере метрики агрегируются по [$host](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-v-host),
и каждая группа выводится как отдельная зона:
```nginx
status_zone $host zone=server_zone:5;
```
В указанной таким образом зоне разделяемой памяти
будет собираться следующая статистика:
| `ssl` | Объект; SSL-метрики.
Присутствует, если в `server` есть `listen ssl;` |
|--------------|-----------------------------------------------------------------------------------------|
| `handshaked` | Число; суммарное количество успешных SSL-рукопожатий |
| `reuses` | Число; суммарное количество повторных использований SSL-сессий во время SSL-рукопожатий |
| `timedout` | Число; суммарное количество SSL-рукопожатий с истекшим таймаутом |
| `failed` | Число; суммарное количество неуспешных SSL-рукопожатий |
| `requests` | Объект; метрики запросов |
| `total` | Число; суммарное количество клиентских запросов |
| `processing` | Число; текущее количество обслуживаемых клиентских запросов |
| `discarded` | Число; суммарное количество запросов завершенных без отправки ответа |
| `responses` | Объект; метрики ответов |
| `` | Число; ненулевое количество ответов со статусом (100-599) |
| `xxx` | Число; ненулевое количество ответов с другим кодом статуса |
| `data` | Объект; метрики данных |
| `received` | Число; суммарное количество байт, полученное от клиентов |
| `sent` | Число; суммарное количество байт, отправленное клиентам |
Пример:
```json
{
"ssl":{
"handshaked":4174,
"reuses":0,
"timedout":0,
"failed":0
},
"requests":{
"total":4327,
"processing":0,
"discarded":0
},
"responses":{
"200":4305,
"302":6,
"304":12,
"404":4
},
"data":{
"received":733955,
"sent":59207757
}
}
```
#### `/status/http/location_zones/<зона>`
Для сбора статистики в контексте [location](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-location) или [if в location](https://angie.software//angie/docs/configuration/modules/http/http_rewrite.md#if)
нужно задать директиву [status_zone](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-status-zone):
```nginx
location / {
root /usr/share/angie/html;
status_zone location_zone;
if ($request_uri ~* "^/condition") {
# ...
status_zone if_location_zone;
}
}
```
Для группировки метрик по пользовательскому значению
используйте альтернативный синтаксис.
В этом примере метрики агрегируются по [$host](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-v-host),
и каждая группа выводится как отдельная зона:
```nginx
status_zone $host zone=server_zone:5;
```
В указанной таким образом зоне разделяемой памяти
будет собираться следующая статистика:
| `requests` | Объект; метрики запросов |
|--------------|----------------------------------------------------------------------|
| `total` | Число; суммарное количество клиентских запросов |
| `discarded` | Число; суммарное количество запросов завершенных без отправки ответа |
| `responses` | Объект; метрики ответов |
| `` | Число; ненулевое количество ответов со статусом (100-599) |
| `xxx` | Число; ненулевое количество ответов с другим кодом статуса |
| `data` | Объект; метрики данных |
| `received` | Число; суммарное количество байт, полученное от клиентов |
| `sent` | Число; суммарное количество байт, отправленное клиентам |
Пример:
```json
{
"requests": {
"total": 4158,
"discarded": 0
},
"responses": {
"200": 4157,
"304": 1
},
"data": {
"received": 538200,
"sent": 177606236
}
}
```
#### `/status/http/metric_zones/<зона>`
Пользовательские метрики, созданные директивами [metric_zone](https://angie.software//adc/docs/load_balancer/reference/http/http_metric.md#adc-metric-zone) или
[metric_complex_zone](https://angie.software//adc/docs/load_balancer/reference/http/http_metric.md#adc-metric-complex-zone) в контексте `http`. Метрики обновляются через
директиву [metric](https://angie.software//adc/docs/load_balancer/reference/http/http_metric.md#adc-metric) или переменные модуля.
| `discarded` | Число; количество отброшенных записей метрик из-за нехватки памяти в зоне. |
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `metrics` | Объект; метрики по ключам. Для зон с одной метрикой значения — числа.
Для сложных зон значения — объекты с именами метрик. Для режима
`histogram` значения — объекты с именами бакетов. |
Если задан `discard_key` и часть записей была истекшей,
агрегированные метрики доступны под этим ключом.
Пример:
```json
{
"discarded": 3,
"metrics": {
"example.com": {
"count": 42,
"max": 8
}
"expired": {
"count": 10,
"max": 3.2
}
}
}
```
### Stream server
#### `/status/stream/server_zones/<зона>`
Для сбора статистики в контексте [server](https://angie.software//adc/docs/load_balancer/reference/stream/stream.md#adc-s-server)
нужно задать директиву [status_zone](https://angie.software//adc/docs/load_balancer/reference/stream/stream.md#adc-s-status-zone):
```nginx
server {
...
status_zone server_zone;
}
```
Для группировки метрик по пользовательскому значению
используйте альтернативный синтаксис.
В этом примере метрики агрегируются по [$host](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-v-host),
и каждая группа выводится как отдельная зона:
```nginx
status_zone $host zone=server_zone:5;
```
В указанной таким образом зоне разделяемой памяти
будет собираться следующая статистика:
| `ssl` | Объект; SSL-метрики.
Присутствует, если в `server` есть `listen ssl;` |
|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| `handshaked` | Число; суммарное количество успешных SSL-рукопожатий |
| `reuses` | Число; суммарное количество повторных использований SSL-сессий во время SSL-рукопожатий |
| `timedout` | Число; суммарное количество SSL-рукопожатий с истекшим таймаутом |
| `failed` | Число; суммарное количество неуспешных SSL-рукопожатий |
| `connections` | Объект; метрики соединений |
| `total` | Число; суммарное количество клиентских соединений |
| `processing` | Число; текущее количество обслуживаемых клиентских соединений |
| `discarded` | Число; суммарное количество клиентских соединений,
завершенных без создания сессии |
| `passed` | Число; суммарное количество клиентских соединений,
переданных на другой прослушивающий порт директивами `pass` |
| `sessions` | Объект; метрики сессий |
| `success` | Число; количество сессий, завершенных с кодом 200, что означает успешное завершение |
| `invalid` | Число; количество сессий, завершенных с кодом 400, случается, когда сервер не может прочитать данные от клиента, например, заголовок PROXY protocol |
| `forbidden` | Число; количество сессий, завершенных с кодом 403, когда доступ запрещен, например, ограничен для определенного адреса клиента |
| `internal_error` | Число; количество сессий, завершенных с кодом 500, внтуренняя ошибка сервера |
| `bad_gateway` | Число; количество сессий, завершенных с кодом 502, Bad Gateway, если, например, сервер в upstream недоступен или не может быть выбран |
| `service_unavailable` | Число; количество сессий, завершенных с кодом 503, Service Unavailable, если, например, доступ ограничен числом входящих соединений |
| `data` | Объект; метрики данных |
| `received` | Число; суммарное количество байт, полученное от клиентов |
| `sent` | Число; суммарное количество байт, отправленное клиентам |
Пример:
```json
{
"ssl": {
"handshaked": 24,
"reuses": 0,
"timedout": 0,
"failed": 0
},
"connections": {
"total": 24,
"processing": 1,
"discarded": 0,
"passed": 2
},
"sessions": {
"success": 24,
"invalid": 0,
"forbidden": 0,
"internal_error": 0,
"bad_gateway": 0,
"service_unavailable": 0
},
"data": {
"received": 2762947,
"sent": 53495723
}
}
```
### HTTP caches
```nginx
proxy_cache cache_zone;
proxy_cache_valid 200 10m;
```
#### `/status/http/caches/`
Для каждой зоны, сконфигурированной в [proxy_cache](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-cache), хранятся следующие
данные:
```json
{
"name_zone": {
"size": 0,
"cold": false,
"hit": {
"responses": 0,
"bytes": 0
},
"stale": {
"responses": 0,
"bytes": 0
},
"updating": {
"responses": 0,
"bytes": 0
},
"revalidated": {
"responses": 0,
"bytes": 0
},
"miss": {
"responses": 0,
"bytes": 0,
"responses_written": 0,
"bytes_written": 0
},
"expired": {
"responses": 0,
"bytes": 0,
"responses_written": 0,
"bytes_written": 0
},
"bypass": {
"responses": 0,
"bytes": 0,
"responses_written": 0,
"bytes_written": 0
}
}
}
```
| `size` | Число; текущий размер кэша |
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `max_size` | Число; ограничение на максимальный размер кэша, если задано в конфигурации |
| `cold` | Логическое значение; `true`, пока загрузчик кэша подгружает данные с диска |
| `hit` | Объект; метрики возвращенных из кэша ответов ([proxy_cache_valid](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-cache-valid)) |
| `responses` | Число; суммарное количество ответов, прочитанных из кэша |
| `bytes` | Число; суммарное количество байт, прочитанных из кэша |
| `stale` | Объект; метрики просроченных ответов, возвращенных из кэша ([proxy_cache_use_stale](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-cache-use-stale)) |
| `responses` | Число; суммарное количество ответов, прочитанных из кэша |
| `bytes` | Число; суммарное количество байт, прочитанных из кэша |
| `updating` | Объект; метрики просроченных ответов, возвращенных из кэша, пока данные в кэше обновляются ([proxy_cache_use_stale](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-cache-use-stale) updating) |
| `responses` | Число; суммарное количество ответов, прочитанных из кэша |
| `bytes` | Число; суммарное количество байт, прочитанных из кэша |
| `revalidated` | Объект; метрики просроченных и ревалидированных ответов, возвращенных из кэша ([proxy_cache_revalidate](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-cache-revalidate)) |
| `responses` | Число; суммарное количество ответов, прочитанных из кэша |
| `bytes` | Число; суммарное количество байт, прочитанных из кэша |
| `miss` | Объект; метрики ответов, не найденных в кэше |
| `responses` | Число; суммарное количество соответствующих ответов |
| `bytes` | Число; суммарное количество байт, прочитанных с проксируемого сервера |
| `responses_written` | Число; суммарное количество ответов, записанных в кэш |
| `bytes_written` | Число; суммарное количество байт, записанных в кэш |
| `expired` | Объект; количество ответов, возвращенных не из кэша, т.к. просрочены |
| `responses` | Число; суммарное количество соответствующих ответов |
| `bytes` | Число; суммарное количество байт, прочитанных с проксируемого сервера |
| `responses_written` | Число; суммарное количество ответов, записанных в кэш |
| `bytes_written` | Число; суммарное количество байт, записанных в кэш |
| `bypass` | Объект; статистика ответов, возвращенных в обход кэша ([proxy_cache_bypass](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-cache-bypass)) |
| `responses` | Число; суммарное количество соответствующих ответов |
| `bytes` | Число; суммарное количество байт, прочитанных с проксируемого сервера |
| `responses_written` | Число; суммарное количество ответов, записанных в кэш |
| `bytes_written` | Число; суммарное количество байт, записанных в кэш |
При включении шардинга кэша с помощью директив
[proxy_cache_path](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-cache-path) отдельные шарды указываются как объекты-члены в объекте
`shards`:
| `shards` | Объект; его члены — отдельные шарды |
|------------|----------------------------------------------------------------------------|
| `` | Объект; представляет отдельный шард, а имя объекта — путь кэша |
| `size` | Число; текущий размер шарда |
| `max_size` | Число; максимальный размер шарда, если задан в конфигурации |
| `cold` | Логическое значение; `true`, пока загрузчик кэша подгружает данные с диска |
```json
{
"name_zone": {
"shards": {
"/path/to/shard1": {
"size": 0,
"cold": false
},
"/path/to/shard2": {
"size": 0,
"cold": false
}
}
}
```
### ACME-клиенты
#### `/status/http/acme_clients/<клиент>`
Для каждого настроенного [acme_client](https://angie.software//adc/docs/load_balancer/reference/http/http_acme.md#adc-acme-client) в блоке `http`
возвращается текущее состояние клиента и сертификата:
```json
{
"state": "ready",
"certificate": "valid",
"details": "The client is ready to request a certificate.",
"next_run": "|sampledateshort|T16:15:43.805Z"
}
```
| `state` | Строка; состояние ACME-клиента. Возможные значения: `ready`,
`requesting`, `disabled`, `failed`. |
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| `certificate` | Строка; состояние сертификата. Возможные значения: `valid`,
`expired`, `missing`, `mismatch`, `error`. |
| `details` | Строка; краткие сведения о последнем действии ACME. |
| `next_run` | Дата; ближайшая запланированная попытка запроса или обновления
сертификата. Не возвращается, когда `state` равно
`disabled` или `requesting`. |
### limit_conn
```nginx
limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m;
```
#### `/status/http/limit_conns/<зона>`, `/status/stream/limit_conns/<зона>`
Каждая из сконфигурированных зон: [limit_conn в http](https://angie.software//angie/docs/configuration/modules/http/http_api.md#limit-conn) или [limit_conn в stream](https://angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#s-limit-conn) содержит следующие данные:
```json
{
"passed": 73,
"skipped": 0,
"rejected": 0,
"exhausted": 0
}
```
| `passed` | Число; суммарное количество переданных на проксируемый сервер соединений |
|-------------|-----------------------------------------------------------------------------------------------|
| `skipped` | Число; суммарное количество соединений, переданных с нулевым или превосходящим 255 байт |
| `rejected` | Число; суммарное количество соединений сверх сконфигурированного ограничения |
| `exhausted` | Число; суммарное количество соединений, сброшенных из-за переполнения хранилища зоны |
### limit_req
```nginx
limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s;
```
#### `/status/http/limit_reqs/<зона>`
Каждая из сконфигурированных зон [limit_req](#adc-limit-req) cодержит следующие данные:
```json
{
"passed": 54816,
"skipped": 0,
"delayed": 65,
"rejected": 26,
"exhausted": 0
}
```
| `passed` | Число; суммарное количество проксированых соединений |
|-------------|-----------------------------------------------------------------------------------------------|
| `skipped` | Число; суммарное количество соединений, переданных с нулевым или превосходящим 255 байт |
| `delayed` | Число; суммарное количество задержанных соединений |
| `rejected` | Число; суммарное количество сброшенных соединений |
| `exhausted` | Число; суммарное количество соединений, сброшенных из-за переполнения хранилища зоны |
### HTTP upstream
Чтобы включить сбор следующих метрик, задайте директиву
[zone](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone)
в контексте [upstream](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-u-upstream),
например:
```nginx
upstream upstream {
zone upstream 256k;
server backend.example.com service=_example._tcp resolve max_conns=5;
keepalive 4;
}
```
#### `/status/http/upstreams/`
где — имя [апстрима](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream), в конфигурации которого указана директива [zone](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone).
```json
{
"peers": {
"192.168.16.4:80": {
"server": "backend.example.com",
"service": "_example._tcp",
"backup": false,
"weight": 5,
"state": "up",
"selected": {
"current": 2,
"total": 232
},
"max_conns": 5,
"responses": {
"200": 222,
"302": 12
},
"data": {
"sent": 543866,
"received": 27349934
},
"health": {
"fails": 0,
"unavailable": 0,
"downtime": 0
},
"sid": ""
}
},
"keepalive": 2
}
```
| `peers` | Объект; содержит метрики всех пиров апстрима во вложенных объектах,
имена которых — канонические представления адресов этих пиров.
Внутри каждого вложенного объекта: |
|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `server` | Строка; сервер, как он указан в директиве [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) |
| `service` | Строка; имя сервиса, указанное в директиве [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server), если сконфигурировано |
| `backup` | Логическое значение; `true` для backup-серверов. |
| `weight` | Число; сконфигурированный [weight](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) |
| `state` | Строка; текущее состояние пира, и какие запросы ему отправляются:
- `busy`: указывает, что число запросов на сервер
достигло ограничения, заданного [max_conns](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server),
и новые запросы на него не отправляются;
- `down`: отключен вручную, не отправляются никакие запросы;
- `recovering`: восстанавливается после сбоя
согласно [slow_start](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#slow-start),
отправляется все больше запросов;
- `unavailable`: достиг предела [max_fails](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails),
отправляются пробные клиентские запросы
с интервалом [fail_timeout](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#fail-timeout);
- `up`: работоспособен, запросы отправляются как обычно;
- `checking`: настроен как `essential` и проверяется,
отправляются только [проверочные запросы](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe);
- `draining`: аналогичен `down`,
но отправляются запросы сессий,
привязанных ранее через [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky);
- `unhealthy`: неработающий,
отправляются только [проверочные запросы](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe). |
| `selected` | Объект; статистика выбора пиров |
| `current` | Число; текущее количество соединений к пиру |
| `total` | Число; общее количество запросов переданных пиру |
| `last` | Строка или число; время последнего выбора пира
в формате [даты](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-date-format) |
| `max_conns` | Число; [максимальное](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) количество одновременных активных соединений к пиру, если сконфигурировано |
| `responses` | Объект; статистика ответов |
| `` | Число; ненулевое количество ответов со статусом (100-599) |
| `xxx` | Число; ненулевое количество ответов с другим кодом статуса |
| `data` | Объект; метрики данных |
| `received` | Число; суммарное количество байт, полученное от пира |
| `sent` | Число; суммарное количество байт, отправленное пиру |
| `health` | Объект; статистика по состоянию пира |
| `fails` | Число; общее количество неудачных попыток работы с пиром |
| `unavailable` | Число; столько раз пир становился `unavailable` по достижении значения [max_fails](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) |
| `downtime` | Число; суммарное время (в миллисекундах), в течение которого пир был недоступен для выбора как `unavailable` |
| `downstart` | Строка или число; время, когда пир стал `unavailable`,
в формате [даты](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-date-format).
Поле присутствует, только пока пир находится в состоянии
`unavailable`; в остальных случаях оно отсутствует |
| `header_time` | Число; среднее время (в миллисекундах)
получения заголовков ответа от сервера;
см. директиву [response_time_factor](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-u-response-time-factor) |
| `response_time` | Число; среднее время (в миллисекундах) получения ответа от сервера;
см. директиву [response_time_factor](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-u-response-time-factor) |
| `sid` | Строка; [id сервера](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve), указанный в конфигурации апстрима |
| `keepalive` | Число; текущее количество кэшированных соединений |
| `backup_switch` | Объект; содержит текущее состояние логики активного резервирования,
присутствует, если для апстрима настроен [backup_switch](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream.md#adc-u-backup-switch) |
| `active` | Число; уровень активной группы,
которая сейчас используется для балансировки запросов.
Если активная группа является основной, значение равно 0 |
| `timeout` | Число; оставшееся время ожидания в миллисекундах,
после которого балансировщик перепроверит на наличие здоровых узлов
группы с меньшим уровнем, начиная с основной,
а группы с большим уровнем не проверяются;
не отображается для основной группы (уровень 0) |
##### `health/probes`
Если для апстрима настроены проверки [upstream_probe](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream_probe.md#adc-u-upstream-probe),
то в объекте `health` также есть вложенный объект `probes`,
содержащий счетчики проверок работоспособности сервера,
а `state`, помимо значений из таблицы выше,
может принимать значения `checking` и `unhealthy`:
```json
{
"192.168.16.4:80": {
"state": "unhealthy",
"...": "...",
"health": {
"...": "...",
"probes": {
"count": 10,
"fails": 10,
"last": "|sampledateshort|T09:56:07Z"
}
}
}
}
```
Значение `checking` у `state` не учитывается в `downtime`
и означает, что сервер,
проверка которого настроена с параметром `essential`,
еще не проверялся;
значение `unhealthy` — что сервер неработающий.
Оба эти состояния также означают, что сервер не участвует в балансировке.
Детали проверок см. в описании [upstream_probe](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe).
Счетчики в `probes`:
| `count` | Число; общее количество проверок этого сервера |
|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `fails` | Число; количество неуспешных проверок |
| `last` | Строка или число; время последней проверки
в формате [даты](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-date-format) |
##### `queue`
Если для апстрима настроена [очередь запросов](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-queue),
то в объекте апстрима также есть вложенный объект `queue`,
содержащий счетчики запросов в очереди:
```json
{
"queue": {
"queued": 20112,
"waiting": 1011,
"dropped": 6031,
"timedout": 560,
"overflows": 13
}
}
```
Значения счетчиков суммируются по всем рабочим процессам:
| `queued` | Число; общее количество запросов, попавших в очередь |
|-------------|--------------------------------------------------------------------------------------------------------------------|
| `waiting` | Число; текущее количество запросов в очереди |
| `dropped` | Число; общее количество запросов, удаленных из очереди из-за того,
что клиент преждевременно закрыл соединение |
| `timedout` | Число; общее количество запросов, удаленных из очереди по таймауту |
| `overflows` | Число; общее количество случаев переполнения очереди |
### Stream upstream
Чтобы включить сбор следующих метрик, задайте директиву
[zone](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone)
в контексте [upstream](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-s-u-upstream),
например:
```nginx
upstream upstream {
zone upstream 256k;
server backend.example.com service=_example._tcp resolve max_conns=5;
keepalive 4;
}
```
#### `/status/stream/upstreams/`
Здесь — имя [апстрима](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream), в конфигурации которого
использована директива [zone](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone).
```json
{
"peers": {
"192.168.16.4:1935": {
"server": "backend.example.com",
"service": "_example._tcp",
"backup": false,
"weight": 5,
"state": "up",
"selected": {
"current": 2,
"total": 232
},
"max_conns": 5,
"data": {
"sent": 543866,
"received": 27349934
},
"health": {
"fails": 0,
"unavailable": 0,
"downtime": 0
}
}
}
}
```
| `peers` | Объект; содержит метрики всех пиров апстрима во вложенных объектах,
имена которых — канонические представления адресов этих пиров.
Внутри каждого вложенного объекта: |
|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `server` | Строка; адрес, заданный директивой [server](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) |
| `service` | Строка; имя сервиса, если оно указано в директиве [server](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) |
| `backup` | Логическое значение; `true` для backup-серверов |
| `weight` | Число; заданный для пира [вес](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) |
| `state` | Строка; текущее состояние пира, и какие запросы ему отправляются:
- `busy`: указывает, что число запросов на сервер
достигло ограничения, заданного [max_conns](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server),
и новые запросы на него не отправляются;
- `down`: отключен вручную, не отправляются никакие запросы;
- `recovering`: восстанавливается после сбоя
согласно [slow_start](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-slow-start),
отправляется все больше запросов;
- `unavailable`: достиг предела [max_fails](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails),
отправляются пробные клиентские запросы
с интервалом [fail_timeout](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-fail-timeout);
- `up`: работоспособен, запросы отправляются как обычно.
- `checking`: настроен как `essential` и проверяется,
отправляются только [проверочные запросы](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe);
- `draining`: аналогичен `down`,
но отправляются запросы сессий,
привязанных ранее через [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky);
- `unhealthy`: неработающий,
отправляются только [проверочные запросы](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe). |
| `selected` | Объект; статистика выбора этого пира для подключения |
| `current` | Число; текущее количество подключений к пиру |
| `total` | Число; общее количество подключений, направленных этому пиру |
| `last` | Строка или число; время, когда пир был выбран в последний раз,
в формате [даты](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-date-format) |
| `max_conns` | Число;
[максимальное](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server)
количество одновременных активных подключений к пиру, если оно задано |
| `data` | Объект; статистика передачи данных |
| `received` | Число; общее количество байт, полученное от пира |
| `sent` | Число; общее количество байт, отправленное пиру |
| `health` | Объект; статистика по состоянию пира |
| `fails` | Число; общее количество неудачных попыток связаться с пиром |
| `unavailable` | Число; общее количество переходов в состояние `unavailable`
по достижении значения [max_fails](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails) |
| `downtime` | Число; общее время в миллисекундах,
в течение которого пир находился в состоянии `unavailable`
(недоступен для выбора) |
| `downstart` | Строка или число; время, когда пир последний раз стал `unavailable`,
в формате [даты](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-date-format).
Поле присутствует, только пока пир находится в состоянии
`unavailable`; в остальных случаях оно отсутствует |
| `connect_time` | Число; среднее время (в миллисекундах)
установления соединения с сервером;
см. директиву [response_time_factor](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-s-u-response-time-factor) |
| `first_byte_time` | Число; среднее время (в миллисекундах)
получения первого байта ответа от сервера;
см. директиву [response_time_factor](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-s-u-response-time-factor) |
| `last_byte_time` | Число; среднее время (в миллисекундах)
получения полного ответа от сервера;
см. директиву [response_time_factor](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-s-u-response-time-factor) |
| `backup_switch` | Объект; содержит текущее состояние логики активного резервирования,
присутствует, если для апстрима настроен [backup_switch](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream.md#adc-s-u-backup-switch) |
| `active` | Число; уровень активной группы,
которая сейчас используется для балансировки запросов.
Если активная группа является основной, значение равно 0 |
| `timeout` | Число; оставшееся время ожидания в миллисекундах,
после которого балансировщик перепроверит на наличие здоровых узлов
группы с меньшим уровнем, начиная с основной,
а группы с большим уровнем не проверяются;
не отображается для основной группы (уровень 0) |
Если для апстрима настроены проверки [upstream_probe](https://angie.software//adc/docs/load_balancer/reference/stream/stream_upstream_probe.md#adc-s-u-upstream-probe),
то в объекте `health` также есть вложенный объект `probes`,
содержащий счетчики проверок работоспособности сервера,
а `state`, помимо значений из таблицы выше,
может принимать значения `checking` и `unhealthy`:
```json
{
"192.168.16.4:80": {
"state": "unhealthy",
"...": "...",
"health": {
"...": "...",
"probes": {
"count": 2,
"fails": 2,
"last": "|sampledateshort|T11:03:54Z"
}
}
}
}
```
Значение `checking` у `state` означает, что сервер,
проверка которого настроена с параметром `essential`,
еще не проверялся;
значение `unhealthy` — что сервер неработающий.
Оба эти состояния также означают, что сервер не участвует в балансировке.
Детали проверок см. в описании [upstream_probe](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe).
Счетчики в `probes`:
| `count` | Число; общее количество проверок этого сервера |
|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `fails` | Число; количество неуспешных проверок |
| `last` | Строка или число; время последней проверки
в формате [даты](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-date-format) |
## API динамической конфигурации
В составе API есть раздел `/config`, позволяющий динамически менять
конфигурацию Angie в формате JSON
с помощью HTTP-запросов `PUT`, `PATCH` и `DELETE`.
Все изменения атомарны: новые настройки применяются целиком
либо не применяются вовсе.
При ошибке Angie сообщит, в чем причина.
### Подразделы `/config`
Cейчас в разделе `/config` доступна настройка отдельных серверов в
составе апстримов для модулей [HTTP](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-http-upstreams-servers)
и [stream](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-stream-upstreams-servers); число настроек, к
которым применима динамическая конфигурация, планомерно увеличивается.
#### `/config/http/upstreams//servers/<имя>`
Позволяет настраивать отдельные серверы в составе апстрима,
в том числе добавлять новые и удалять настроенные.
Параметры в составе пути URI:
| `` | Имя блока `upstream`;
чтобы настраивать его через `/config`,
в нем должна быть задана директива [zone](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone),
определяющая зону разделяемой памяти. |
|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `<имя>` | Имя конкретного сервера в составе указанного ``;
задается в формате `@`, где:
- `@` — необязательная часть,
задающая имя сервиса в целях разрешения SRV-записей.
- `` — доменное имя сервиса (при наличии resolve)
или IP-адрес; также можно указать порт. |
Например, для следующей конфигурации:
```nginx
upstream backend {
server backend.example.com service=_http._tcp resolve;
server 127.0.0.1;
zone backend 1m;
}
```
Допустимы такие имена серверов:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/_http._tcp@backend.example.com/
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/127.0.0.1:80/
```
Этот подраздел API позволяет задавать параметры `weight`,
`max_conns`, `max_fails`, `fail_timeout`, `slow_start`, `backup`,
`down` и `sid`, описанные в разделе [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server).
#### NOTE
Отдельного параметра `drain` здесь нет;
включить режим `drain` можно,
задав для `down` строковое значение `drain`:
```console
$ curl -X PUT -d \"drain\" \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/down
```
Пример:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on
```
```json
{
"weight": 1,
"max_conns": 0,
"max_fails": 1,
"fail_timeout": 10,
"slow_start": 0,
"backup": true,
"down": false,
"sid": ""
}
```
Фактически доступны будут только те параметры, которые поддерживает
текущий метод балансировки нагрузки [апстрима](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream).
Так, если апстрим настроен с методом балансировки `random`:
```nginx
upstream backend {
zone backend 256k;
server backend.example.com resolve max_conns=5;
random;
}
```
То добавить в него новый сервер с параметром `backup` невозможно:
```console
$ curl -X PUT -d '{ "backup": true }' \
http://127.0.0.1/config/http/upstreams/backend/servers/backend1.example.com
```
```json
{
"error": "FormatError",
"description": "The \"backup\" field is unknown."
}
```
#### NOTE
Даже с совместимым методом балансировки параметр `backup`
можно задать лишь при добавлении нового сервера.
#### `/config/stream/upstreams//servers/<имя>`
Позволяет настраивать отдельные серверы в составе апстрима,
в том числе добавлять новые и удалять настроенные.
Параметры в составе пути URI:
| `` | Имя блока `upstream`;
чтобы настраивать его через `/config`,
в нем должна быть задана директива [zone](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone),
определяющая зону разделяемой памяти. |
|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `<имя>` | Имя конкретного сервера в составе указанного ``;
задается в формате `@`, где:
- `@` — необязательная часть,
задающая имя сервиса в целях разрешения SRV-записей.
- `` — доменное имя сервиса (при наличии resolve)
или IP-адрес; также можно указать порт. |
Например, для следующей конфигурации:
```nginx
upstream backend {
server backend.example.com:8080 service=_example._tcp resolve;
server 127.0.0.1:12345;
zone backend 1m;
}
```
Допустимы такие имена серверов:
```console
$ curl http://127.0.0.1/config/stream/upstreams/backend/servers/_example._tcp@backend.example.com:8080/
$ curl http://127.0.0.1/config/stream/upstreams/backend/servers/127.0.0.1:12345/
```
Этот подраздел API позволяет задавать параметры `weight`,
`max_conns`, `max_fails`, `fail_timeout`, `slow_start`, `backup` и
`down`, описанные в разделе [server](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server).
#### NOTE
Отдельного параметра `drain` здесь нет;
включить режим `drain` можно,
задав для `down` строковое значение `drain`:
```console
$ curl -X PUT -d \"drain\" \
http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com/down
```
Пример:
```console
curl http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com?defaults=on
```
```json
{
"weight": 1,
"max_conns": 0,
"max_fails": 1,
"fail_timeout": 10,
"slow_start": 0,
"backup": true,
"down": false,
}
```
Фактически доступны будут только те параметры, которые поддерживает
текущий метод балансировки нагрузки [апстрима](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream).
Так, если апстрим настроен с методом балансировки `random`:
```nginx
upstream backend {
zone backend 256k;
server backend.example.com resolve max_conns=5;
random;
}
```
То добавить в него новый сервер с параметром `backup` невозможно:
```console
$ curl -X PUT -d '{ "backup": true }' \
http://127.0.0.1/config/stream/upstreams/backend/servers/backend1.example.com
```
```json
{
"error": "FormatError",
"description": "The \"backup\" field is unknown."
}
```
#### NOTE
Даже с совместимым методом балансировки параметр `backup`
можно задать лишь при добавлении нового сервера.
При удалении серверов можно установить аргумент
`connection_drop=<значение>`, чтобы переопределить настройки
[proxy_connection_drop](https://angie.software//adc/docs/load_balancer/reference/stream/stream_proxy.md#adc-s-proxy-connection-drop):
```console
$ curl -X DELETE \
http://127.0.0.1/config/stream/upstreams/backend/servers/backend1.example.com?connection_drop=off
$ curl -X DELETE \
http://127.0.0.1/config/stream/upstreams/backend/servers/backend2.example.com?connection_drop=on
$ curl -X DELETE \
http://127.0.0.1/config/stream/upstreams/backend/servers/backend3.example.com?connection_drop=1000
```
### HTTP-методы
Рассмотрим семантику каждого из применимых к этому разделу HTTP-методов
на примере следующей конфигурации апстрима:
```nginx
http {
# ...
upstream backend {
zone upstream 256k;
server backend.example.com resolve max_conns=5;
# ...
}
server {
# ...
location /config/ {
api /config/;
allow 127.0.0.1;
deny all;
}
}
}
```
#### GET
HTTP-метод `GET` позволяет запросить сущность по любому существующему пути
в пределах `/config` так же, как это делается в других разделах API.
Например, для ветки серверов апстрима
`/config/http/upstreams/backend/servers/`
допустимы такие запросы:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_conns
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
$ curl http://127.0.0.1/config/http/upstreams/backend/servers
$ # ...
$ curl http://127.0.0.1/config
```
Получить параметры по умолчанию можно с аргументом `defaults=on`:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers?defaults=on
```
```json
{
"backend.example.com": {
"weight": 1,
"max_conns": 5,
"max_fails": 1,
"fail_timeout": 10,
"slow_start": 0,
"backup": false,
"down": false,
"sid": ""
}
}
```
#### PUT
HTTP-метод `PUT` позволяет создать новую JSON-сущность по указанному пути
или *полностью* заменить существующую.
Например, чтобы добавить не заданный ранее параметр `max_fails`
у сервера `backend.example.com` в апстриме `backend`:
```console
$ curl -X PUT -d '2' \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails
```
```json
{
"success": "Updated",
"description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was updated with replacing."
}
```
Проверим изменения:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```
```json
{
"max_conns": 5,
"max_fails": 2
}
```
#### DELETE
HTTP-метод `DELETE` удаляет *ранее заданные* настройки по указанному пути;
при этом восстанавливаются значения по умолчанию, если они есть.
Например, чтобы удалить измененный ранее параметр `max_fails`
у сервера `backend.example.com` в апстриме `backend`:
```console
$ curl -X DELETE \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails
```
```console
{
"success": "Reset",
"description": "Configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was reset to default."
}
```
Проверим изменения с аргументом `defaults=on`:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on
```
```json
{
"weight": 1,
"max_conns": 5,
"max_fails": 1,
"fail_timeout": 10,
"slow_start": 0,
"backup": false,
"down": false,
"sid": ""
}
```
Параметр `max_fails` вернулся к значению по умолчанию.
При удалении серверов можно установить аргумент
`connection_drop=<значение>`, чтобы переопределить настройки
[proxy_connection_drop](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-connection-drop), [grpc_connection_drop](https://angie.software//adc/docs/load_balancer/reference/http/http_grpc.md#adc-grpc-connection-drop),
[fastcgi_connection_drop](https://angie.software//adc/docs/load_balancer/reference/http/http_fastcgi.md#adc-fastcgi-connection-drop), [scgi_connection_drop](https://angie.software//adc/docs/load_balancer/reference/http/http_scgi.md#adc-scgi-connection-drop) и
[uwsgi_connection_drop](https://angie.software//adc/docs/load_balancer/reference/http/http_uwsgi.md#adc-uwsgi-connection-drop):
```console
$ curl -X DELETE \
http://127.0.0.1/config/http/upstreams/backend/servers/backend1.example.com?connection_drop=off
$ curl -X DELETE \
http://127.0.0.1/config/http/upstreams/backend/servers/backend2.example.com?connection_drop=on
$ curl -X DELETE \
http://127.0.0.1/config/http/upstreams/backend/servers/backend3.example.com?connection_drop=1000
```
#### PATCH
HTTP-метод `PATCH` позволяет создать новую сущность по указанному пути
либо частично заменить или дополнить существующую
([RFC 7386](https://datatracker.ietf.org/doc/html/rfc7396)),
отправив в данных JSON-определение.
Метод работает так: если сущности, указанные в новом определении, уже есть
в конфигурации, они будут перезаписаны; если их нет, то они будут добавлены.
Например, чтобы поменять значение параметра `down` у сервера
`backend.example.com` в апстриме `backend`,
оставив прочее без изменений:
```console
$ curl -X PATCH -d '{ "down": true }' \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```
```json
{
"success": "Updated",
"description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging."
}
```
Проверим изменения:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```
```json
{
"max_conns": 5,
"down": true
}
```
Обратите внимание, что переданный с запросом `PATCH` JSON-объект *слился*
с уже существующим, а не заменил его целиком, как было бы с `PUT`.
Особый случай представляют значения `null`; они используются для удаления
отдельных элементов конфигурации в ходе такого слияния.
#### NOTE
Такое удаление аналогично действию `DELETE`;
в частности, восстанавливаются значения по умолчанию.
Например, чтобы удалить добавленный ранее параметр `down`
и одновременно с этим изменить `max_conns`:
```console
$ curl -X PATCH -d '{ "down": null, "max_conns": 6 }' \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```
```json
{
"success": "Updated",
"description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging."
}
```
Проверим изменения:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```
```json
{
"max_conns": 6
}
```
Параметр `down`, для которого было передано значение `null`, удален;
значение `max_conns` изменено.
# https://angie.software/adc/docs/load_balancer/reference/http/http_auth_basic.md
# Auth Basic
Позволяет ограничить доступ к ресурсам с проверкой имени и пароля пользователя по протоколу "HTTP Basic Authentication".
Ограничить доступ можно также по [адресу](https://angie.software//angie/docs/configuration/modules/http/http_access.md#http-access) или по [результату подзапроса](https://angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request). Одновременное ограничение доступа по адресу и паролю управляется директивой [satisfy](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-satisfy).
## Пример конфигурации
```nginx
location / {
auth_basic "closed site";
auth_basic_user_file conf/htpasswd;
}
```
## Директивы
### auth_basic
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_basic` строка | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `auth_basic off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, limit_except |
Включает проверку имени и пароля пользователя по протоколу "HTTP Basic Authentication". Заданный параметр используется в качестве realm. В значении параметра допустимо использование переменных.
| `off` | отменяет действие унаследованной с предыдущего уровня конфигурации директивы auth_basic |
|---------|-------------------------------------------------------------------------------------------|
### auth_basic_user_file
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_basic_user_file` файл; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, limit_except |
Задает файл, в котором хранятся имена и пароли пользователей. Формат файла следующий:
```none
# комментарий
имя1:пароль1
имя2:пароль2:комментарий
имя3:пароль3
```
В имени файла можно использовать переменные.
Поддерживаются следующие типы паролей:
* зашифрованные функцией crypt(); могут быть созданы с помощью утилиты `htpasswd` из дистрибутива HTTP-сервера Apache или команды "openssl passwd";
* хэшированные с помощью алгоритма, основанного на MD5, по версии Apache (apr1); могут быть созданы теми же инструментами;
* заданные согласно синтаксису "{схема}данные" как описано в [RFC 2307](https://datatracker.ietf.org/doc/html/rfc2307#section-5.3); в настоящий момент реализованы схемы PLAIN (в качестве примера, не следует применять), SHA (простое SHA-1 хэширование, не следует применять) и SSHA (SHA-1 хэширование с солью, используется в некоторых программах, в частности OpenLDAP и Dovecot).
#### WARNING
Поддержка схемы SHA была добавлена лишь для облегчения процесса миграции файлов паролей с других веб-серверов. Ее не следует применять для новых паролей, т.к. используемое при этом SHA-1 хэширование без соли уязвимо к взлому при помощи [радужных таблиц](http://en.wikipedia.org/wiki/Rainbow_attack).
# https://angie.software/adc/docs/load_balancer/reference/http/http_auth_request.md
# Auth Request
Предоставляет возможность авторизации клиента, основанной на результате подзапроса. Если подзапрос возвращает код ответа 2xx, доступ разрешается. Если 401 или 403 — доступ запрещается с соответствующим кодом ошибки. Любой другой код ответа, возвращаемый подзапросом, считается ошибкой.
При ошибке 401 клиенту также передается заголовок `WWW-Authenticate` из ответа подзапроса.
## Пример конфигурации
```nginx
location /private/ {
auth_request /auth;
# ...
}
location = /auth {
proxy_pass ...;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
}
```
## Директивы
### auth_request
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_request` `uri` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `auth_request off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Включает авторизацию, основанную на результате выполнения подзапроса, и задает URI, на который будет отправлен подзапрос.
### auth_request_set
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_request_set` $переменная значение; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Устанавливает переменную в запросе в заданное значение после завершения запроса авторизации. Значение может содержать переменные из запроса авторизации, например, $upstream_http_\*.
# https://angie.software/adc/docs/load_balancer/reference/http/http_autoindex.md
# AutoIndex
Обслуживает запросы, оканчивающиеся косой чертой (`/`), и выдает листинг каталога. Обычно запрос попадает к модулю `AutoIndex`, когда модуль [Index](https://angie.software//angie/docs/configuration/modules/http/http_index.md#http-index) не нашел индексный файл.
## Пример конфигурации
```nginx
location / {
autoindex on;
}
```
## Директивы
### autoindex
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `autoindex` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `autoindex off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает вывод листинга каталога.
### autoindex_exact_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `autoindex_exact_size` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `autoindex_exact_size on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Для [формата](https://angie.software//angie/docs/configuration/modules/http/http_autoindex.md#autoindex-format) HTML определяет, как выводить размеры файлов в листинге каталога: точно или округляя до килобайт, мегабайт и гигабайт.
### autoindex_format
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `autoindex_format` `html` | `xml` | `json` | `jsonp`; |
|------------------------------------------------------------------------------------------|---------------------------------------------------------|
| По умолчанию | `autoindex_format html;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает формат вывода листинга каталога.
При использовании формата JSONP имя callback-функции задается в аргументе запроса `callback`. Если аргумент отсутствует или имеет пустое значение, то используется формат JSON.
Вывод в формате XML может быть преобразован при помощи модуля [XSLT](https://angie.software//angie/docs/configuration/modules/http/http_xslt.md#http-xslt).
### Форматы вывода
Поля объекта в ответах содержат следующие данные:
| Поле | Описание |
|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `name` | Имя файла или каталога |
| `type` | Тип объекта: `file` или `directory` |
| `size` | Размер объекта согласно [autoindex_exact_size](https://angie.software//angie/docs/configuration/modules/http/http_autoindex.md#autoindex-exact-size);
для каталогов — `0` |
| `mtime` | Время последнего изменения в формате Unix time |
HTML
```html
Index of /files/
Index of /files/
../
example.txt 12-Jun-2025 14:21 1234
image.png 12-Jun-2025 14:21 4321
```
XML
```xml
example.txt
file
1234
2025-06-12T14:21:00Z
image.png
file
4321
2025-06-12T14:21:00Z
```
JSON
```json
[
{
"name": "example.txt",
"type": "file",
"size": 1234,
"mtime": "2025-06-12T14:21:00Z"
},
{
"name": "image.png",
"type": "file",
"size": 4321,
"mtime": "2025-06-12T14:21:00Z"
}
]
```
JSONP
```javascript
callback([
{
"name": "example.txt",
"type": "file",
"size": 1234,
"mtime": "2025-06-12T14:21:00Z"
},
{
"name": "image.png",
"type": "file",
"size": 4321,
"mtime": "2025-06-12T14:21:00Z"
}
]);
```
### autoindex_localtime
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `autoindex_localtime` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `autoindex_localtime off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Для [формата](https://angie.software//angie/docs/configuration/modules/http/http_autoindex.md#autoindex-format) HTML определяет, в какой временной зоне выводить время в листинге каталога: в локальной или в UTC.
# https://angie.software/adc/docs/load_balancer/reference/http/http_browser.md
# Browser
Создает переменные, значения которых зависят от значения поля `User-Agent` в заголовке запроса.
## Переменные
### `$modern_browser`
равна значению, заданному директивой [modern_browser_value](#adc-modern-browser-value), если браузер опознан как современный;
### `$ancient_browser`
равна значению, заданному директивой [ancient_browser_value](#adc-ancient-browser-value), если браузер опознан как устаревший;
### `$msie`
равна "1", если браузер опознан как MSIE любой версии.
## Пример конфигурации
### Выбор индексного файла:
```nginx
modern_browser_value "modern.";
modern_browser msie 5.5;
modern_browser gecko 1.0.0;
modern_browser opera 9.0;
modern_browser safari 413;
modern_browser konqueror 3.0;
index index.${modern_browser}html index.html;
```
### Перенаправление для старых браузеров:
```nginx
modern_browser msie 5.0;
modern_browser gecko 0.9.1;
modern_browser opera 8.0;
modern_browser safari 413;
modern_browser konqueror 3.0;
modern_browser unlisted;
ancient_browser Links Lynx netscape4;
if ($ancient_browser) {
rewrite ^ /ancient.html;
}
```
## Директивы
### ancient_browser
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ancient_browser` строка ...; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает подстроки, при нахождении которых в поле `User-Agent` заголовка запроса браузер считается устаревшим. Специальная строка "netscape4" соответствует регулярному выражению "^Mozilla/[1-4]".
### ancient_browser_value
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ancient_browser_value` строка; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `ancient_browser_value 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает значение для переменных [$ancient_browser](#adc-v-ancient-browser).
### modern_browser
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `modern_browser` браузер версия;
`modern_browser` `unlisted`; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает версию браузера, начиная с которой он считается современным. В качестве браузера можно задать msie, gecko (браузеры, созданные на основе Mozilla), opera, safari или konqueror.
Версии можно задать в форматах X, X.X, X.X.X или X.X.X.X. Максимальные значения для каждого из форматов соответственно — 4000, 4000.99, 4000.99.99 и 4000.99.99.99.
Специальное значение `unlisted` указывает считать современным браузер, не описанный директивами modern_browser и [ancient_browser](#adc-ancient-browser). В противном случае неперечисленный браузер будет считаться устаревшим. Если в заголовке запроса нет поля `User-Agent`, то браузер считается неперечисленным.
### modern_browser_value
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `modern_browser_value` строка; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `modern_browser_value 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает значение для переменных [$modern_browser](#adc-v-modern-browser).
# https://angie.software/adc/docs/load_balancer/reference/http/http_charset.md
# Charset
Добавляет указанную кодировку в поле `Content-Type` заголовка ответа. Кроме того, модуль может перекодировать данные из одной кодировки в другую с некоторыми ограничениями:
* перекодирование осуществляется только в одну сторону — от сервера к клиенту,
* перекодироваться могут только однобайтные кодировки
* или однобайтные кодировки в UTF-8 и обратно.
## Пример конфигурации
```nginx
include conf/koi-win;
charset windows-1251;
source_charset koi8-r;
```
## Директивы
### charset
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `charset` кодировка | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `charset off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Добавляет указанную кодировку в поле `Content-Type` заголовка ответа. Если эта кодировка отличается от указанной в директиве [source_charset](#adc-source-charset), то выполняется перекодирование.
Параметр `off` отменяет добавление кодировки в поле `Content-Type` заголовка ответа.
Кодировка может быть задана с помощью переменной:
```nginx
charset $charset;
```
В этом случае необходимо, чтобы все возможные значения переменной присутствовали хотя бы один раз в любом месте конфигурации в виде директив [charset_map](#adc-charset-map), charset или [source_charset](#adc-source-charset). Для кодировок utf-8, windows-1251 и koi8-r для этого достаточно включить в конфигурацию файлы conf/koi-win, conf/koi-utf и conf/win-utf. Для других кодировок можно просто сделать фиктивную таблицу перекодировки, например:
```nginx
charset_map iso-8859-5 _ { }
```
Кроме того, кодировка может быть задана в поле `X-Accel-Charset` заголовка ответа. Эту возможность можно запретить с помощью директив [proxy_ignore_headers](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-ignore-headers), [fastcgi_ignore_headers](https://angie.software//adc/docs/load_balancer/reference/http/http_fastcgi.md#adc-fastcgi-ignore-headers), [uwsgi_ignore_headers](https://angie.software//adc/docs/load_balancer/reference/http/http_uwsgi.md#adc-uwsgi-ignore-headers), [scgi_ignore_headers](https://angie.software//adc/docs/load_balancer/reference/http/http_scgi.md#adc-scgi-ignore-headers) и [grpc_ignore_headers](https://angie.software//adc/docs/load_balancer/reference/http/http_grpc.md#adc-grpc-ignore-headers).
### charset_map
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `charset_map` кодировка1 кодировка2 { ... } |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Описывает таблицу перекодирования из одной кодировки в другую. Таблица для обратного перекодирования строится на основании тех же данных. Коды символов задаются в шестнадцатеричном виде. Неописанные символы в пределах 80-FF заменяются на "?". При перекодировании из UTF-8 символы, отсутствующие в однобайтной кодировке, заменяются на "&#XXXX;".
Пример:
```nginx
charset_map koi8-r windows-1251 {
C0 FE ; # small yu
C1 E0 ; # small a
C2 E1 ; # small b
C3 F6 ; # small ts
}
```
При описании таблицы перекодирования в UTF-8, коды кодировки UTF-8 должны быть указаны во второй колонке, например:
```nginx
charset_map koi8-r utf-8 {
C0 D18E ; # small yu
C1 D0B0 ; # small a
C2 D0B1 ; # small b
C3 D186 ; # small ts
}
```
Полные таблицы преобразования из koi8-r в windows-1251 и из koi8-r и windows-1251 в utf-8 входят в дистрибутив и находятся в файлах conf/koi-win, conf/koi-utf и conf/win-utf.
### charset_types
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `charset_types` mime-тип ...; |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
| По умолчанию | `charset_types text/html text/xml text/plain text/vnd.wap.wml application/javascript application/rss+xml;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает работу модуля в ответах с указанными MIME-типами в дополнение к `text/html`. Специальное значение `*` соответствует любому MIME-типу.
### override_charset
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `override_charset` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `override_charset off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Определяет, выполнять ли перекодирование для ответов, полученных от проксированного сервера или от FastCGI/uwsgi/SCGI/gRPC-сервера, если в ответах уже указана кодировка в поле `Content-Type` заголовка ответа. Если перекодирование разрешено, то в качестве исходной кодировки используется кодировка, указанная в полученном ответе.
#### NOTE
Если ответ был получен в подзапросе, то, независимо от значения директивы override_charset, всегда выполняется перекодирование из кодировки ответа в кодировку основного запроса.
### source_charset
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `source_charset` кодировка; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Задает исходную кодировку ответа. Если эта кодировка отличается от указанной в директиве [charset](#adc-charset), то выполняется перекодирование.
# https://angie.software/adc/docs/load_balancer/reference/http/http_dav.md
# DAV
Предназначен для автоматизации задач управления файлами на сервере по протоколу WebDAV. Модуль обрабатывает HTTP- и WebDAV-методы PUT, DELETE, MKCOL, COPY и MOVE.
#### NOTE
WebDAV-клиенты, которые требуют для работы дополнительных WebDAV-методов, не будут работать с этим модулем.
## Пример конфигурации
```nginx
location / {
root /data/www;
client_body_temp_path /data/client_temp;
dav_methods PUT DELETE MKCOL COPY MOVE;
create_full_put_path on;
dav_access group:rw all:r;
limit_except GET {
allow 192.168.1.0/32;
deny all;
}
}
```
## Директивы
### create_full_put_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `create_full_put_path` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `create_full_put_path off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
По спецификации WebDAV-метод PUT может создавать файл только в уже существующем каталоге. Данная директива разрешает создавать все необходимые промежуточные каталоги.
### dav_access
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `dav_access` пользователи:права ...; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `dav_access user:rw;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает права доступа для создаваемых файлов и каталогов, например,
```nginx
dav_access user:rw group:rw all:r;
```
Если заданы какие-либо права для group или all, то права для user указывать необязательно:
```nginx
dav_access group:rw all:r;
```
### dav_methods
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `dav_methods` `off` | метод ...; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `dav_methods off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает указанные HTTP- и WebDAV-методы. Параметр `off` запрещает все методы, обрабатываемые данным модулем. Поддерживаются следующие методы: PUT, DELETE, MKCOL, COPY и MOVE.
Файл, загружаемый методом PUT, записывается во временный файл, а потом этот файл переименовывается. Временный файл и его постоянное место хранения могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешевой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой системе, что и каталог с временными файлами, задаваемый директивой [client_body_temp_path](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-client-body-temp-path) для данного `location`.
При создании файла с помощью метода PUT можно задать дату модификации, передав ее в поле заголовка `Date`.
### min_delete_depth
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `min_delete_depth` число; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `min_delete_depth 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает методу DELETE удалять файлы при условии, что число элементов в пути запроса не меньше заданного. Например, директива
```nginx
min_delete_depth 4;
```
разрешает удалять файлы по запросам
```console
/users/00/00/name
/users/00/00/name/pic.jpg
/users/00/00/page.html
```
и запрещает удаление
```console
/users/00/00
```
# https://angie.software/adc/docs/load_balancer/reference/http/http_empty_gif.md
# Empty GIF
Выдает однопиксельный прозрачный GIF.
## Пример конфигурации
```nginx
location = /_.gif {
empty_gif;
}
```
## Директивы
### empty_gif
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `empty_gif`; |
|------------------------------------------------------------------------------------------|----------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Разрешает в содержащем location выдавать однопиксельный прозрачный GIF.
# https://angie.software/adc/docs/load_balancer/reference/http/http_fastcgi.md
# FastCGI
Позволяет передавать запросы FastCGI-серверу.
## Пример конфигурации
```nginx
location / {
fastcgi_pass localhost:9000;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
fastcgi_param QUERY_STRING $query_string;
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;
}
```
## Директивы
### fastcgi_bind
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_bind` адрес [`transparent`] | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает локальный IP-адрес с необязательным портом, который будет использоваться в исходящих соединениях с FastCGI-сервером. В значении параметра допустимо использование переменных. Специальное значение `off` отменяет действие унаследованной с предыдущего уровня конфигурации директивы fastcgi_bind, позволяя системе самостоятельно выбирать локальный IP-адрес и порт.
Параметр `transparent` позволяет задать нелокальный IP-адрес, который будет использоваться в исходящих соединениях с FastCGI-сервером, например, реальный IP-адрес клиента:
```nginx
fastcgi_bind $remote_addr transparent;
```
Для работы параметра обычно требуется запустить рабочие процессы Angie с привилегиями [суперпользователя](https://angie.software//angie/docs/configuration/modules/core.md#user). В Linux это не требуется, так как если указан параметр transparent, то рабочие процессы наследуют capability CAP_NET_RAW из главного процесса.
#### NOTE
Необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с FastCGI-сервера.
### fastcgi_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_buffer_size` размер; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `fastcgi_buffer_size 4k|8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает размер буфера, в который будет читаться первая часть ответа, получаемого от FastCGI-сервера. В этой части ответа обычно находится небольшой заголовок ответа. По умолчанию размер одного буфера равен размеру страницы памяти. В зависимости от платформы это или 4K, или 8K, однако его можно сделать меньше.
### fastcgi_buffering
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_buffering` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `fastcgi_buffering on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает использовать буферизацию ответов FastCGI-сервера.
| `on` | Angie принимает ответ FastCGI-сервера как можно быстрее, сохраняя его в
буферы, заданные директивами [fastcgi_buffer_size](#adc-fastcgi-buffer-size) и
[fastcgi_buffers](#adc-fastcgi-buffers). Отправка клиенту при этом выполняется
параллельно: заполненные буферы передаются на отправку (никто их не
удерживает), но суммарно не более значения
[fastcgi_busy_buffers_size](#adc-fastcgi-busy-buffers-size). Если буфер заполнен не полностью, то
на отправку он не передается, если только это не последние данные
ответа. Поэтому для моментальной передачи каждых нескольких байт режим
буферизированного чтения не подходит. Если ответ не вмещается целиком в
память, то его часть может быть записана на диск во [временный файл](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-temp-path). Запись во временные файлы контролируется
директивами [fastcgi_max_temp_file_size](#adc-fastcgi-max-temp-file-size) и
[fastcgi_temp_file_write_size](#adc-fastcgi-temp-file-write-size). |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | Ответ передается клиенту сразу же по мере его поступления. Angie
работает в цикле «прочитал — отправил» и не ждет, пока буфер заполнится
целиком: например, прочитанные 10 байт из буфера 4К будут сразу
отправлены клиенту. При этом если весь ответ умещается в буфер, Angie
может прочитать его целиком. Максимальный размер данных, который Angie
может принять от сервера за один раз, задается директивой
[fastcgi_buffer_size](#adc-fastcgi-buffer-size). При `off` не работает
[fastcgi_limit_rate](#adc-fastcgi-limit-rate). |
Буферизация может быть также включена или выключена путем передачи значения "yes" или "no" в поле `X-Accel-Buffering` заголовка ответа. Эту возможность можно запретить с помощью директивы [fastcgi_ignore_headers](#adc-fastcgi-ignore-headers).
### fastcgi_buffers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_buffers` число размер; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `fastcgi_buffers 8 4k | 8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число и размер буферов для одного соединения, в которые будет читаться ответ, получаемый от FastCGI-сервера.
По умолчанию размер одного буфера равен размеру страницы. В зависимости от платформы это или 4K, или 8K.
### fastcgi_busy_buffers_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_busy_buffers_size` размер; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `fastcgi_busy_buffers_size 8k | 16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
При включенной [буферизации](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-buffering) ответов FastCGI-сервера, ограничивает суммарный размер буферов, которые могут быть заняты для отправки ответа клиенту, пока ответ еще не прочитан целиком. Оставшиеся буферы тем временем могут использоваться для чтения ответа и, при необходимости, буферизации части ответа во временный файл. По умолчанию размер ограничен двумя буферами, заданными директивами [fastcgi_buffer_size](#adc-fastcgi-buffer-size) и [fastcgi_buffers](#adc-fastcgi-buffers).
### fastcgi_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache` зона | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `fastcgi_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает зону разделяемой памяти, используемую для кэширования. Одна и та же зона может использоваться в нескольких местах. В значении параметра можно использовать переменные. Параметр `off` запрещает кэширование, унаследованное с предыдущего уровня конфигурации.
### fastcgi_cache_background_update
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_background_update` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| По умолчанию | `fastcgi_cache_background_update off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запустить фоновый подзапрос для обновления просроченного элемента кэша, в то время как клиенту возвращается устаревший кэшированный ответ. Использование устаревшего кэшированного ответа в момент его обновления должно быть [разрешено](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-cache-use-stale-updating).
### fastcgi_cache_bypass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_bypass` строка ...; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает условия, при которых ответ не будет браться из кэша. Если значение хотя бы одного из строковых параметров непустое и не равно "0", то ответ не берется из кэша:
```nginx
fastcgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
fastcgi_cache_bypass $http_pragma $http_authorization;
```
Можно использовать совместно с директивой [fastcgi_no_cache](#adc-fastcgi-no-cache).
### fastcgi_cache_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_key` строка; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает ключ для кэширования, например,
```nginx
fastcgi_cache_key localhost:9000$request_uri;
```
### fastcgi_cache_lock
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_lock` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `fastcgi_cache_lock off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если включено, одновременно только одному запросу будет позволено заполнить новый элемент кэша, идентифицируемый согласно директиве [fastcgi_cache_key](#adc-fastcgi-cache-key), передав запрос на FastCGI-сервер. Остальные запросы этого же элемента будут либо ожидать появления ответа в кэше, либо освобождения блокировки этого элемента, в течение времени, заданного директивой [fastcgi_cache_lock_timeout](#adc-fastcgi-cache-lock-timeout).
### fastcgi_cache_lock_age
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_lock_age` время; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `fastcgi_cache_lock_age 5s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если последний запрос, переданный на FastCGI-сервер для заполнения нового элемента кэша, не завершился за указанное время, на FastCGI-сервер может быть передан еще один запрос.
### fastcgi_cache_lock_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_lock_timeout` время; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `fastcgi_cache_lock_timeout 5s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут для [fastcgi_cache_lock](#adc-fastcgi-cache-lock). По истечении указанного времени запрос будет передан на FastCGI-сервер, однако ответ не будет кэширован.
### fastcgi_cache_max_range_offset
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_max_range_offset` число; |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает смещение в байтах для запросов с указанием диапазона запрашиваемых байт (byte-range requests). Если диапазон находится за указанным смещением, range-запрос будет передан на FastCGI-сервер и ответ не будет кэширован.
### fastcgi_cache_methods
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_methods` `GET` | `HEAD` | `POST` ...; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------|
| По умолчанию | `fastcgi_cache_methods GET HEAD;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если метод запроса клиента указан в этой директиве, то ответ будет кэширован. Методы "GET" и "HEAD" всегда добавляются в список, но тем не менее рекомендуется перечислять их явно. См. также директиву [fastcgi_no_cache](#adc-fastcgi-no-cache).
### fastcgi_cache_min_uses
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_min_uses` число; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `fastcgi_cache_min_uses 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число запросов, после которого ответ будет кэширован.
#### WARNING
Метаданные кэша хранятся в разделяемой памяти. Ручное удаление файлов кэша не
сбрасывает счетчики и может привести к непредсказуемому поведению. Для
полного сброса остановите сервер, удалите директорию кэша и запустите снова.
#### NOTE
Сторонние модули очистки кэша (например, [Cache Purge](https://angie.software//angie/docs/installation/external-modules/cache-purge.md#external-cache-purge)) удаляют только
файлы, но не сбрасывают счетчик fastcgi_cache_min_uses. Директива
предназначена для защиты кэша от загрязнения редкими запросами, и сброс
счетчика при очистке может негативно повлиять на производительность.
### fastcgi_cache_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_path` путь [`levels=`уровни] [`use_temp_path=``on` | `off`] `keys_zone=`имя:размер [`inactive=`время] [`max_size=`размер] [`min_free=`размер] [`manager_files=`число] [`manager_sleep=`время] [`manager_threshold=`время] [`loader_files=`число] [`loader_sleep=`время] [`loader_threshold=`время]; |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает путь и другие параметры кэша. Данные кэша хранятся в файлах. Ключом и именем файла в кэше является результат функции MD5 от проксированного URL.
Параметр `levels` задает уровни иерархии кэша: можно задать от 1 до 3 уровней, на каждом уровне допускаются значения 1 или 2. Например, при использовании
```nginx
fastcgi_cache_path /data/angie/cache levels=1:2 keys_zone=one:10m;
```
имена файлов в кэше будут такого вида:
```nginx
/data/angie/cache/c/29/b7f54b2df7773722d382f4809d65029c
```
Кэшируемый ответ сначала записывается во временный файл, а потом этот файл переименовывается. Временные файлы и кэш могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешевой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если кэш будет находиться на той же файловой системе, что и каталог с временными файлами.
Какой из каталогов будет использоваться для временных файлов определяется параметром `use_temp_path`.
| `on` | Если параметр не задан или установлен в значение "on", будет использоваться каталог, задаваемый директивой [fastcgi_temp_path](#adc-fastcgi-temp-path) для данного location. |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | временные файлы будут располагаться непосредственно в каталоге кэша. |
Кроме того, все активные ключи и информация о данных хранятся в зоне разделяемой памяти, имя и размер которой задаются параметром `keys_zone`. Зоны размером в 1 мегабайт достаточно для хранения около 8 тысяч ключей. Метаданные кэша хранятся в разделяемой памяти.
Если к данным кэша не обращаются в течение времени, заданного параметром `inactive`, то данные удаляются, независимо от их свежести.
По умолчанию `inactive` равен 10 минутам.
Специальный процесс **менеджера кэша** следит за максимальным размером кэша, а также за минимальным объемом свободного места на файловой системе с кэшем, и удаляет наименее востребованные данные при превышении максимального размера кэша или недостаточном объеме свободного места. Удаление данных происходит итерациями.
| `max_size` | максимальное пороговое значение размера кэша |
|---------------------|--------------------------------------------------------------------------------------------------------|
| `min_free` | минимальное пороговое значение объема свободного места на файловой системе с кэшем |
| `manager_files` | максимальное количество удаляемых элементов кэша за одну итерацию
По умолчанию: `100` |
| `manager_threshold` | ограничивает время работы одной итерации
По умолчанию: `200` миллисекунд |
| `manager_sleep` | время, в течение которого выдерживается пауза между итерациями
По умолчанию: `50` миллисекунд |
Через минуту после старта Angie активируется специальный процесс **загрузчика кэша**, который загружает в зону кэша информацию о ранее кэшированных данных, хранящихся на файловой системе. Загрузка также происходит итерациями.
| `loader_files` | максимальное количество элементов кэша к загрузке в одну итерацию
По умолчанию: `100` |
|--------------------|--------------------------------------------------------------------------------------------------------|
| `loader_threshold` | ограничивает время работы одной итерации
По умолчанию: `200` миллисекунд |
| `loader_sleep` | время, в течение которого выдерживается пауза между итерациями
По умолчанию: `50` миллисекунд |
### fastcgi_cache_revalidate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_revalidate` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `fastcgi_cache_revalidate off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает ревалидацию просроченных элементов кэша при помощи условных запросов с полями заголовка `If-Modified-Since` и `If-None-Match` .
### fastcgi_cache_use_stale
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_use_stale` `error` | `timeout` | `invalid_header` | `updating` | `http_500` | `http_503` | `http_403` | `http_429` | `off` ...; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `fastcgi_cache_use_stale off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, в каких случаях можно использовать устаревший кэшированный ответ. Параметры директивы совпадают с параметрами директивы [fastcgi_next_upstream](#adc-fastcgi-next-upstream).
| `error` | позволяет использовать устаревший кэшированный ответ при невозможности выбора FastCGI-сервера для обработки запроса. |
|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `updating` | дополнительный параметр, разрешает использовать устаревший кэшированный ответ, если на данный момент он уже обновляется. Это позволяет минимизировать число обращений к FastCGI-серверам при обновлении кэшированных данных. |
Использование устаревшего кэшированного ответа может также быть разрешено непосредственно в заголовке ответа на определенное количество секунд после того, как ответ устарел.
* Расширение [stale-while-revalidate](https://datatracker.ietf.org/doc/html/rfc5861#section-3) поля заголовка `Cache-Control` разрешает использовать устаревший кэшированный ответ, если на данный момент он уже обновляется.
* Расширение [stale-if-error](https://datatracker.ietf.org/doc/html/rfc5861#section-4) поля заголовка `Cache-Control` разрешает использовать устаревший кэшированный ответ в случае ошибки.
#### NOTE
Такой способ менее приоритетен, чем задание параметров директивы.
Чтобы минимизировать число обращений к FastCGI-серверам при заполнении нового элемента кэша, можно воспользоваться директивой [fastcgi_cache_lock](#adc-fastcgi-cache-lock).
### fastcgi_cache_valid
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_cache_valid` [код ...] время; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает время кэширования для разных кодов ответа. Например, директивы
```nginx
fastcgi_cache_valid 200 302 10m;
fastcgi_cache_valid 404 1m;
```
задают время кэширования 10 минут для ответов с кодами 200 и 302 и 1 минуту для ответов с кодом 404.
Если указано только время кэширования,
```nginx
fastcgi_cache_valid 5m;
```
то кэшируются только ответы 200, 301 и 302.
Кроме того, можно кэшировать любые ответы с помощью параметра `any`:
```nginx
fastcgi_cache_valid 200 302 10m;
fastcgi_cache_valid 301 1h;
fastcgi_cache_valid any 1m;
```
#### NOTE
Параметры кэширования могут также быть заданы непосредственно в заголовке ответа. Такой способ приоритетнее, чем задание времени кэширования с помощью директивы.
* Поле заголовка `X-Accel-Expires` задает время кэширования ответа в секундах. Значение 0 запрещает кэшировать ответ. Если значение начинается с префикса @, оно задает абсолютное время в секундах с начала эпохи, до которого ответ может быть кэширован.
* Если в заголовке нет поля `X-Accel-Expires`, параметры кэширования определяются по полям заголовка `Expires` или `Cache-Control`.
* Ответ, в заголовке которого есть поле `Set-Cookie`, не будет кэшироваться.
* Ответ, в заголовке которого есть поле `Vary` со специальным значением "\*", не будет кэшироваться. Ответ, в заголовке которого есть поле `Vary` с другим значением, будет кэширован с учетом соответствующих полей заголовка запроса.
Обработка одного или более из этих полей заголовка может быть отключена при помощи директивы [fastcgi_ignore_headers](#adc-fastcgi-ignore-headers).
### fastcgi_catch_stderr
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_catch_stderr` строка; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает строку для поиска в потоке ошибок ответа, полученного от FastCGI-сервера. Если строка найдена, то считается, что FastCGI-сервер вернул [неверный](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-next-upstream) ответ. Это позволяет обрабатывать ошибки приложений в Angie, например:
```nginx
location /php/ {
fastcgi_pass backend:9000;
...
fastcgi_catch_stderr "PHP Fatal error";
fastcgi_next_upstream error timeout invalid_header;
}
```
### fastcgi_connect_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_connect_timeout` время; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `fastcgi_connect_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут для установления соединения с FastCGI-сервером. Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.
### fastcgi_connection_drop
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_connection_drop` время | `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| По умолчанию | `fastcgi_connection_drop off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Настраивает завершение всех соединений с проксируемым сервером,
если он был удален из группы или помечен как постоянно недоступный
в результате процесса [reresolve](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve)
или [команды API](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods) `DELETE`.
Соединение завершается, когда обрабатывается следующее событие чтения или записи
для клиента или проксируемого сервера.
Установка времени включает [таймаут](https://angie.software//angie/docs/configuration/configfile.md#syntax) до завершения соединения;
при выборе значения `on` соединения завершаются немедленно.
### fastcgi_force_ranges
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_force_ranges` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `fastcgi_force_ranges off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Включает поддержку диапазонов запрашиваемых байт (byte-range) для кэшированных и некэшированных ответов FastCGI-сервера вне зависимости от наличия поля `Accept-Ranges` в заголовках этих ответов.
### fastcgi_hide_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_hide_header` поле; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
По умолчанию Angie не передает клиенту поля заголовка `Status` и `X-Accel-...` из ответа FastCGI-сервера. Директива fastcgi_hide_header задает дополнительные поля, которые не будут передаваться. Если же передачу полей нужно разрешить, можно воспользоваться директивой [fastcgi_pass_header](#adc-fastcgi-pass-header).
### fastcgi_ignore_client_abort
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_ignore_client_abort` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| По умолчанию | `fastcgi_ignore_client_abort off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, закрывать ли соединение с FastCGI-сервером в случае, если клиент закрыл соединение, не дождавшись ответа.
### fastcgi_ignore_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_ignore_headers` поле; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Запрещает обработку некоторых полей заголовка из ответа FastCGI-сервера. В директиве можно указать поля `X-Accel-Redirect`, `X-Accel-Expires`, `X-Accel-Limit-Rate`, `X-Accel-Buffering`, `X-Accel-Charset`, `Expires`, `Cache-Control`, `Set-Cookie` и `Vary`.
Если не запрещено, обработка этих полей заголовка заключается в следующем:
* `X-Accel-Expires`, `Expires`, `Cache-Control`, `Set-Cookie` и `Vary` задают [параметры кэширования](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-cache-valid) ответа;
* `X-Accel-Redirect` производит [внутреннее перенаправление](https://angie.software//angie/docs/configuration/modules/http/index.md#internal) на указанный URI;
* `X-Accel-Limit-Rate` задает [ограничение скорости](https://angie.software//angie/docs/configuration/modules/http/index.md#limit-rate) передачи ответа клиенту;
* `X-Accel-Buffering` включает или выключает [буферизацию](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-buffering) ответа;
* `X-Accel-Charset` задает желаемую [кодировку](https://angie.software//angie/docs/configuration/modules/http/http_charset.md#id3) ответа.
### fastcgi_index
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_index` имя; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает имя файла, который при создании переменной [$fastcgi_script_name](#adc-v-fastcgi-script-name) будет добавляться после URI, если URI заканчивается косой чертой. Например, при таких настройках
```nginx
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
```
и запросе `/page.php` параметр SCRIPT_FILENAME будет равен `/home/www/scripts/php/page.php`,
а при запросе `/` - `/home/www/scripts/php/index.php`.
### fastcgi_intercept_errors
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_intercept_errors` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `fastcgi_intercept_errors off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, передавать ли клиенту ответы FastCGI-сервера с кодом больше либо равным 300, или же перехватывать их и перенаправлять на обработку Angie с помощью директивы [error_page](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-error-page).
### fastcgi_keep_conn
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_keep_conn` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `fastcgi_keep_conn off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
По умолчанию FastCGI-сервер будет закрывать соединение сразу же после отправки ответа. При установке значения `on` Angie указывает FastCGI-серверу оставлять соединения открытыми. Это в частности требуется для функционирования [постоянных соединений](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive) с FastCGI-серверами.
### fastcgi_limit_rate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_limit_rate` скорость; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `fastcgi_limit_rate 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает скорость чтения ответа от проксируемого сервера.
Скорость задается в байтах в секунду; можно использовать переменные.
| `0` | отключает ограничение скорости |
|-------|----------------------------------|
#### NOTE
Ограничение устанавливается на запрос, поэтому, если Angie одновременно откроет два соединения к FastCGI-серверу, суммарная скорость будет вдвое выше заданного ограничения. Ограничение работает только в случае, если включена [буферизация](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-buffering) ответов FastCGI-сервера.
### fastcgi_max_temp_file_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_max_temp_file_size` размер; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `fastcgi_max_temp_file_size 1024m;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если включена [буферизация](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-buffering) ответов FastCGI-сервера, и ответ не вмещается целиком в буферы, заданные директивами [fastcgi_buffer_size](#adc-fastcgi-buffer-size) и [fastcgi_buffers](#adc-fastcgi-buffers), часть ответа может быть записана во временный файл. Эта директива задает максимальный размер временного файла. Размер данных, сбрасываемых во временный файл за один раз, задается директивой [fastcgi_temp_file_write_size](#adc-fastcgi-temp-file-write-size).
| `0` | отключает возможность буферизации ответов во временные файлы |
|-------|----------------------------------------------------------------|
#### NOTE
Данное ограничение не распространяется на ответы, которые будут [кэшированы](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-cache) или сохранены [на диске](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-store).
### fastcgi_next_upstream
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_next_upstream` `error` | `timeout` | `invalid_header` | `http_500` | `http_503` | `http_403` | `http_404` | `http_429` | `non_idempotent` | `off` ...; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `fastcgi_next_upstream error timeout;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, в каких случаях запрос будет передан следующему серверу:
| `error` | произошла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `timeout` | произошел таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
| `invalid_header` | сервер вернул пустой или неверный ответ; |
| `http_500` | сервер вернул ответ с кодом 500; |
| `http_503` | сервер вернул ответ с кодом 503; |
| `http_403` | сервер вернул ответ с кодом 403; |
| `http_404` | сервер вернул ответ с кодом 404; |
| `http_429` | сервер вернул ответ с кодом 429; |
| `non_idempotent` | обычно запросы с [неидемпотентным](https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2) методом (POST, LOCK, PATCH) не передаются на другой сервер, если запрос серверу группы уже был отправлен; включение параметра явно разрешает повторять подобные запросы; |
| `off` | запрещает передачу запроса следующему серверу. |
#### NOTE
Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту еще ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа, то исправить это уже невозможно.
Директива также определяет, что считается [неудачной попыткой](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) работы с сервером.
| `error`
`timeout`
`invalid_header` | всегда считаются неудачными попытками, даже если они не указаны в директиве |
|--------------------------------------------------------|-------------------------------------------------------------------------------|
| `http_500`
`http_503`
`http_429` | считаются неудачными попытками, только если они указаны в директиве |
| `http_403`
`http_404` | никогда не считаются неудачными попытками |
Передача запроса следующему серверу может быть ограничена по [количеству попыток](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-next-upstream-tries) и по [времени](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-next-upstream-timeout).
### fastcgi_next_upstream_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_next_upstream_timeout` время; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `fastcgi_next_upstream_timeout 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает время, в течение которого возможна передача запроса [следующему серверу](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-next-upstream).
| `0` | отключает это ограничение |
|-------|-----------------------------|
### fastcgi_next_upstream_tries
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_next_upstream_tries` число; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `fastcgi_next_upstream_tries 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает число допустимых попыток для передачи запроса [следующему серверу](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-next-upstream).
| `0` | отключает это ограничение |
|-------|-----------------------------|
### fastcgi_no_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_no_cache` строка ...; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает условия, при которых ответ не будет сохраняться в кэш. Если значение хотя бы одного из строковых параметров непустое и не равно "0", то ответ не будет сохранен:
```nginx
fastcgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
fastcgi_no_cache $http_pragma $http_authorization;
```
Можно использовать совместно с директивой [fastcgi_cache_bypass](#adc-fastcgi-cache-bypass).
### fastcgi_param
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_param` параметр значение [`if_not_empty`]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает параметр, который будет передаваться FastCGI-серверу. В качестве значения можно использовать текст, переменные и их комбинации. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы fastcgi_param.
#### NOTE
В стандартных файлах `fastcgi.conf` и `fastcgi_params`, поставляемых
с Angie, параметр `REQUEST_METHOD` задаётся как
`$upstream_request_method`. Это позволяет при конвертации
`HEAD` в `GET` при кэшировании использовать корректный метод
для запроса к upstream.
Ниже приведен пример минимально необходимых параметров для PHP:
```nginx
fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
fastcgi_param QUERY_STRING $query_string;
```
Параметр SCRIPT_FILENAME используется в PHP для определения имени скрипта, а в параметре QUERY_STRING передаются параметры запроса.
Если скрипты обрабатывают запросы POST, то нужны еще три параметра:
```nginx
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;
```
Если PHP был собран с параметром конфигурации `--enable-force-cgi-redirect`, то нужно передавать параметр REDIRECT_STATUS со значением "200":
```nginx
fastcgi_param REDIRECT_STATUS 200;
```
Если директива указана с `if_not_empty`, такой параметр с пустым значением передаваться на сервер не будет:
```nginx
fastcgi_param HTTPS $https if_not_empty;
```
### fastcgi_pass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_pass` адрес; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location, if в location |
Задает адрес FastCGI-сервера. Адрес может быть указан в виде доменного имени или IP-адреса, и порта:
```nginx
fastcgi_pass localhost:9000;
```
или в виде пути UNIX-сокета:
```nginx
fastcgi_pass unix:/tmp/fastcgi.socket;
```
Если доменному имени соответствует несколько адресов, то все они будут использоваться по очереди (round-robin). И, кроме того, адрес может быть [группой серверов](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).
В значении параметра можно использовать переменные. В этом случае, если адрес указан в виде доменного имени, имя ищется среди описанных [групп серверов](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) и если не найдено, то определяется с помощью [resolver](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-resolver)'а.
#### NOTE
Если `fastcgi_pass` стоит в `location` с косой чертой в конце префикса
(например, `location /name/`),
и при этом в директиве [auto_redirect](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-auto-redirect) указано `default`,
запросы без косой черты в конце будут перенаправляться (`/name -> /name/`).
### fastcgi_pass_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_pass_header` поле; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает передавать от FastCGI-сервера клиенту [запрещенные для передачи](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-hide-header) поля заголовка.
### fastcgi_pass_request_body
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_pass_request_body` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запретить передачу исходного тела запроса на FastCGI-сервер. См. также директиву [fastcgi_pass_request_headers](#adc-fastcgi-pass-request-headers).
### fastcgi_pass_request_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_pass_request_headers` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запретить передачу полей заголовка исходного запроса на FastCGI-сервер. См. также директиву [fastcgi_pass_request_body](#adc-fastcgi-pass-request-body).
### fastcgi_read_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_read_timeout` время; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `fastcgi_read_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при чтении ответа FastCGI-сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени FastCGI-сервер ничего не передаст, соединение закрывается.
### fastcgi_request_buffering
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_request_buffering` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | `fastcgi_request_buffering on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает использовать буферизацию тела запроса клиента.
| `on` | тело запроса полностью [читается](https://angie.software//angie/docs/configuration/modules/http/index.md#client-body-buffer-size) от клиента перед отправкой запроса на FastCGI-сервер. |
|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | тело запроса отправляется на FastCGI-сервер сразу же по мере его поступления. В этом случае запрос не может быть передан [следующему серверу](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-next-upstream), если Angie уже начал отправку тела запроса. |
### fastcgi_send_lowat
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_send_lowat` размер; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `fastcgi_send_lowat 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
При установке директивы в ненулевое значение Angie будет пытаться
минимизировать число операций отправки на исходящих соединениях с
FastCGI-сервером либо при помощи флага `NOTE_LOWAT` метода [kqueue](https://angie.software//angie/docs/configuration/processing.md#kqueue), либо при помощи параметра сокета `SO_SNDLOWAT`, с указанным
размером.
#### NOTE
Эта директива игнорируется на Linux, Solaris и Windows.
### fastcgi_send_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_send_timeout` время; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `fastcgi_send_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при передаче запроса FastCGI-серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени FastCGI-сервер не примет новых данных, соединение закрывается.
### fastcgi_socket_keepalive
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_socket_keepalive` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `fastcgi_socket_keepalive off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Конфигурирует поведение "TCP keepalive" для исходящих соединений к FastCGI-серверу.
| `""` | По умолчанию для сокета действуют настройки операционной системы. |
|--------|---------------------------------------------------------------------|
| `on` | для сокета включается параметр SO_KEEPALIVE |
### fastcgi_split_path_info
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_split_path_info` regex; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Задает регулярное выражение, выделяющее значение для переменной [$fastcgi_path_info](#adc-v-fastcgi-path-info). Регулярное выражение должно иметь две группы захвата, из которых первая становится значением переменной [$fastcgi_script_name](#adc-v-fastcgi-script-name), а вторая — значением переменной [$fastcgi_path_info](#adc-v-fastcgi-path-info). Например, при таких настройках
```default
location ~ ^(.+\.php)(.*)$ {
fastcgi_split_path_info ^(.+\.php)(.*)$;
fastcgi_param SCRIPT_FILENAME /path/to/php$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;
```
и запросе `/show.php/article/0001` параметр SCRIPT_FILENAME будет равен `/path/to/php/show.php`,
а параметр PATH_INFO - `/article/0001`.
### fastcgi_store
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_store` `on` | `off` | строка; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `fastcgi_store off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает сохранение на диск файлов.
| `on` | сохраняет файлы в соответствии с путями, указанными в директивах [alias](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-alias) или [root](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-root) |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | запрещает сохранение файлов |
Кроме того, имя файла можно задать явно с помощью строки с переменными:
```nginx
fastcgi_store /data/www$original_uri;
```
Время изменения файлов выставляется согласно полученному полю `Last-Modified` в заголовке ответа. Ответ сначала записывается во временный файл, а потом этот файл переименовывается. Временный файл и постоянное место хранения ответа могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешевой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой системе, что и каталог с временными файлами, задаваемый директивой [fastcgi_temp_path](#adc-fastcgi-temp-path) для данного location.
Директиву можно использовать для создания локальных копий статических неизменяемых файлов, например:
```nginx
location /images/ {
root /data/www;
error_page 404 = /fetch$uri;
}
location /fetch/ {
internal;
fastcgi_pass backend:9000;
...
fastcgi_store on;
fastcgi_store_access user:rw group:rw all:r;
fastcgi_temp_path /data/temp;
alias /data/www/;
}
```
### fastcgi_store_access
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_store_access` пользователи:права ...; |
|------------------------------------------------------------------------------------------|--------------------------------------------------|
| По умолчанию | `fastcgi_store_access user:rw;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает права доступа для создаваемых файлов и каталогов, например,
```nginx
fastcgi_store_access user:rw group:rw all:r;
```
Если заданы какие-либо права для group или all, то права для user указывать необязательно:
```nginx
fastcgi_store_access group:rw all:r;
```
### fastcgi_temp_file_write_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_temp_file_write_size` размер; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `fastcgi_temp_file_write_size 8k|16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает размер данных, сбрасываемых во временный файл за один раз, при включенной буферизации ответов FastCGI-сервера во временные файлы. По умолчанию размер ограничен двумя буферами, заданными директивами [fastcgi_buffer_size](#adc-fastcgi-buffer-size) и [fastcgi_buffers](#adc-fastcgi-buffers). Максимальный размер временного файла задается директивой [fastcgi_max_temp_file_size](#adc-fastcgi-max-temp-file-size).
### fastcgi_temp_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `fastcgi_temp_path` путь [уровень1 [уровень2 [уровень3]]]\`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `fastcgi_temp_path fastcgi_temp;`
(путь зависит от [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-fastcgi-temp-path`) |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает имя каталога для хранения временных файлов с данными, полученными от FastCGI-серверов. В каталоге может использоваться иерархия подкаталогов до трех уровней. Например, при такой конфигурации
```nginx
fastcgi_temp_path /spool/angie/fastcgi_temp 1 2;
```
временный файл будет следующего вида:
```nginx
/spool/angie/fastcgi_temp/7/45/00000123457
```
См. также параметр use_temp_path директивы [fastcgi_cache_path](#adc-fastcgi-cache-path).
## Параметры, передаваемые FastCGI-серверу
Поля заголовка HTTP-запроса передаются FastCGI-серверу в виде параметров. В приложениях и скриптах, запущенных в виде FastCGI-сервера, эти параметры обычно доступны в виде переменных среды. Например, поле заголовка `User-Agent` передается как параметр HTTP_USER_AGENT. Кроме полей заголовка HTTP-запроса можно передавать произвольные параметры с помощью директивы [fastcgi_param](#adc-fastcgi-param).
## Встроенные переменные
В модуле http_fastcgi есть встроенные переменные, которые можно использовать для формирования параметров с помощью директивы [fastcgi_param](#adc-fastcgi-param):
### `$fastcgi_script_name`
URI запроса или же, если URI заканчивается косой чертой, то URI запроса, дополненное именем индексного файла, задаваемого директивой [fastcgi_index](#adc-fastcgi-index). Эту переменную можно использовать для задания параметров SCRIPT_FILENAME и PATH_TRANSLATED, используемых, в частности, для определения имени скрипта в PHP. Например, для запроса `/info/` и при использовании директив
```nginx
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
```
параметр SCRIPT_FILENAME будет равен `/home/www/scripts/php/info/index.php`.
При использовании директивы [fastcgi_split_path_info](#adc-fastcgi-split-path-info) переменная $fastcgi_script_name равна значению первой группы захвата, задаваемой этой директивой.
### `$fastcgi_path_info`
значение второй группы захвата, задаваемой директивой [fastcgi_split_path_info](#adc-fastcgi-split-path-info). Эту переменную можно использовать для задания параметра PATH_INFO.
# https://angie.software/adc/docs/load_balancer/reference/http/http_flv.md
# FLV
Обеспечивает серверную поддержку псевдо-стриминга для файлов Flash Video (FLV).
Он специальным образом обрабатывает запросы с аргументом `start` в строке запроса, посылая в ответ содержимое файла с запрошенного смещения в байтах, добавив перед ним FLV-заголовок.
## Пример конфигурации
```nginx
location ~ \.flv$ {
flv;
}
```
## Директивы
### flv
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `flv`; |
|------------------------------------------------------------------------------------------|----------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Включает в содержащем location обработку этим модулем.
# https://angie.software/adc/docs/load_balancer/reference/http/http_geo.md
# Geo
Создает переменные, значения которых зависят от IP-адреса клиента.
## Пример конфигурации
```nginx
geo $geo {
default 0;
127.0.0.1 2;
192.168.1.0/24 1;
10.1.0.0/16 1;
::1 2;
2001:0db8::/32 1;
}
```
## Директивы
### geo
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `geo` [$адрес] $переменная { ... } |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Описывает для указанной переменной зависимость значения от IP-адреса клиента. По умолчанию адрес берется из переменной [$remote_addr](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-v-remote-addr), но его также можно получить из другой переменной, например:
```nginx
geo $arg_remote_addr $geo {
...;
}
```
#### NOTE
Поскольку переменные вычисляются только в момент использования, само по себе наличие даже большого числа объявлений переменных `geo` не влечет за собой никаких дополнительных расходов на обработку запросов.
Если значение переменной не представляет собой правильный IP-адрес, то используется адрес "255.255.255.255".
Адреса задаются либо префиксами в формате CIDR (включая одиночные адреса), либо в виде диапазонов.
Также поддерживаются следующие специальные параметры:
| `delete` | удаляет описанную сеть |
|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `default` | значение переменной, если адрес клиента не соответствует ни одному из заданных адресов. При задании адресов в формате CIDR вместо default можно использовать "0.0.0.0/0" и "::/0". Если параметр default не указан, значением по умолчанию будет пустая строка. |
| `include` | включает файл с адресами и значениями. Включений может быть несколько. |
| `proxy` | задает доверенные адреса, при запросе с которых будет использоваться адрес в переданном поле заголовка запроса `X-Forwarded-For`. В отличие от обычных адресов, доверенные адреса проверяются последовательно. |
| `proxy_recursive` | включает рекурсивный поиск адреса. При выключенном рекурсивном поиске вместо исходного адреса клиента, совпадающего с одним из доверенных адресов, будет использоваться последний адрес, переданный в `X-Forwarded-For`. При включенном рекурсивном поиске вместо исходного адреса клиента, совпадающего с одним из доверенных адресов, будет использоваться последний не доверенный адрес, переданный в `X-Forwarded-For`. |
| `ranges` | указывает, что адреса задаются в виде диапазонов. Этот параметр должен быть первым. Для ускорения загрузки гео-базы нужно располагать адреса в порядке возрастания. |
| `volatile` | указывает, что переменная не кэшируется. |
Пример:
```nginx
geo $country {
default ZZ;
include conf/geo.conf;
delete 127.0.0.0/16;
proxy 192.168.100.0/24;
proxy 2001:0db8::/32;
127.0.0.0/24 US;
127.0.0.1/32 RU;
10.1.0.0/16 RU;
192.168.1.0/24 UK;
}
```
В файле `conf/geo.conf` могут быть такие строки:
```console
10.2.0.0/16 RU;
192.168.2.0/24 RU;
```
В качестве значения выбирается максимальное совпадение, например, для адреса `127.0.0.1` будет выбрано значение `RU`, а не `US`.
Пример описания диапазонов:
```nginx
geo $country {
ranges;
default ZZ;
127.0.0.0-127.0.0.0 US;
127.0.0.1-127.0.0.1 RU;
127.0.0.2-127.0.0.255 US;
10.1.0.0-10.1.255.255 RU;
192.168.1.0-192.168.1.255 UK;
}
```
# https://angie.software/adc/docs/load_balancer/reference/http/http_grpc.md
# gRPC
Позволяет передавать запросы gRPC-серверу.
#### NOTE
Для работы этого модуля необходим модуль [HTTP2](https://angie.software//angie/docs/configuration/modules/http/http_v2.md#http-v2).
## Пример конфигурации
```nginx
server {
listen 9000;
http2 on;
location / {
grpc_pass 127.0.0.1:9000;
}
}
```
## Директивы
### grpc_bind
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_bind` адрес [`transparent`] | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает локальный IP-адрес с необязательным портом, который будет использоваться в исходящих соединениях с gRPC-сервером. В значении параметра допустимо использование переменных. Специальное значение `off` отменяет действие унаследованной с предыдущего уровня конфигурации директивы grpc_bind, позволяя системе самостоятельно выбирать локальный IP-адрес и порт.
Параметр `transparent` позволяет задать нелокальный IP-aдрес, который будет использоваться в исходящих соединениях с gRPC-сервером, например, реальный IP-адрес клиента:
```nginx
grpc_bind $remote_addr transparent;
```
Для работы параметра обычно требуется запустить рабочие процессы Angie с привилегиями [суперпользователя](https://angie.software//angie/docs/configuration/modules/core.md#user). В Linux это не требуется, так как если указан параметр transparent, то рабочие процессы наследуют capability CAP_NET_RAW из главного процесса.
#### NOTE
Необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с gRPC-сервера.
### grpc_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_buffer_size` размер; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `grpc_buffer_size 4k|8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает размер буфера, в который будет читаться первая часть ответа, получаемого от gRPC-сервера. Ответ синхронно передается клиенту сразу же по мере его поступления.
### grpc_connect_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_connect_timeout` время; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `grpc_connect_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут для установления соединения с gRPC-сервером. Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.
### grpc_connection_drop
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_connection_drop` время | `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| По умолчанию | `grpc_connection_drop off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Настраивает завершение всех соединений с проксируемым сервером,
если он был удален из группы или помечен как постоянно недоступный
в результате процесса [reresolve](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve)
или [команды API](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods) `DELETE`.
Соединение завершается, когда обрабатывается следующее событие чтения или записи
для клиента или проксируемого сервера.
Установка времени включает [таймаут](https://angie.software//angie/docs/configuration/configfile.md#syntax) до завершения соединения;
при выборе значения `on` соединения завершаются немедленно.
### grpc_hide_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_hide_header` поле; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
По умолчанию Angie не передает клиенту поля заголовка `Date`, `Server` и `X-Accel-...` из ответа gRPC-сервера. Директива `grpc_hide_header` задает дополнительные поля, которые не будут передаваться. Если же передачу полей нужно разрешить, можно воспользоваться директивой [grpc_pass_header](#adc-grpc-pass-header).
### grpc_ignore_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ignore_headers` поле ...; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Запрещает обработку некоторых полей заголовка из ответа gRPC-сервера. В директиве можно указать поля `X-Accel-Redirect` и `X-Accel-Charset`.
Если не запрещено, обработка этих полей заголовка заключается в следующем:
* `X-Accel-Redirect` производит [внутреннее перенаправление](https://angie.software//angie/docs/configuration/modules/http/index.md#internal) на указанный URI;
* `X-Accel-Charset` задает желаемую [кодировку](https://angie.software//angie/docs/configuration/modules/http/http_charset.md#id3) ответа.
### grpc_intercept_errors
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_intercept_errors` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `grpc_intercept_errors off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, передавать ли клиенту ответы gRPC-сервера с кодом больше либо равным 300, или же перехватывать их и перенаправлять на обработку Angie с помощью директивы [error_page](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-error-page).
### grpc_next_upstream
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_next_upstream` `error` | `timeout` | `invalid_header` | `http_500` | `http_502` | `http_503` | `http_504` | `http_403` | `http_404` | `http_429` | `non_idempotent` | `off` ...; |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `grpc_next_upstream error timeout;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, в каких случаях запрос будет передан следующему в группе [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) серверу:
| `error` | произошла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `timeout` | произошел таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
| `invalid_header` | сервер вернул пустой или неверный ответ; |
| `http_500` | сервер вернул ответ с кодом 500; |
| `http_502` | сервер вернул ответ с кодом 502; |
| `http_503` | сервер вернул ответ с кодом 503; |
| `http_504` | сервер вернул ответ с кодом 504; |
| `http_403` | сервер вернул ответ с кодом 403; |
| `http_404` | сервер вернул ответ с кодом 404; |
| `http_429` | сервер вернул ответ с кодом 429; |
| `non_idempotent` | обычно запросы с [неидемпотентным](https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2) методом (POST, LOCK, PATCH) не передаются на другой сервер, если запрос серверу группы уже был отправлен; включение параметра явно разрешает повторять подобные запросы; |
| `off` | запрещает передачу запроса следующему серверу. |
#### NOTE
Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту еще ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа клиенту, то действие директивы на такой запрос не распространяется.
Директива также определяет, что считается [неудачной попыткой](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) работы с сервером.
| `error`, `timeout`, `invalid_header` | всегда считаются неудачными попытками, даже если они не указаны в директиве |
|------------------------------------------------------------|-------------------------------------------------------------------------------|
| `http_500`, `http_502`, `http_503`, `http_504`, `http_429` | считаются неудачными попытками, только если они указаны в директиве |
| `http_403`, `http_404` | никогда не считаются неудачными попытками |
Передача запроса следующему серверу может быть ограничена по [количеству попыток](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-next-upstream-tries) и по [времени](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-next-upstream-timeout).
### grpc_next_upstream_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_next_upstream_timeout` время; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `grpc_next_upstream_timeout 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает время, в течение которого возможна передача запроса [следующему](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### grpc_next_upstream_tries
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_next_upstream_tries` число; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `grpc_next_upstream_tries 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает число допустимых попыток для передачи запроса [следующему](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### grpc_pass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_pass` адрес; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location, if в location |
Задает адрес gRPC-сервера. Адрес может быть указан в виде доменного имени или IP-адреса, и порта:
```nginx
grpc_pass localhost:9000;
```
или в виде пути UNIX-сокета:
```nginx
grpc_pass unix:/tmp/grpc.socket;
```
Также может использоваться схема `grpc://`:
```nginx
grpc_pass grpc://127.0.0.1:9000;
```
Для использования gRPC по SSL необходимо использовать схему `grpcs://`:
```nginx
grpc_pass grpcs://127.0.0.1:443;
```
Если доменному имени соответствует несколько адресов, то все они будут использоваться по очереди (round-robin). Кроме того, в качестве адреса можно указать [группу серверов](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).
В значении параметра можно использовать переменные. В этом случае, если адрес указан в виде доменного имени, имя ищется среди описанных групп серверов и если не найдено, то определяется с помощью [resolver](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-resolver)'а.
#### NOTE
Если `grpc_pass` стоит в `location` с косой чертой в конце префикса
(например, `location /name/`),
и при этом в директиве [auto_redirect](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-auto-redirect) указано `default`,
запросы без косой черты в конце будут перенаправляться (`/name -> /name/`).
### grpc_pass_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_pass_header` поле; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает передавать от gRPC-сервера клиенту [запрещенные для передачи](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-hide-header) поля заголовка.
### grpc_read_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_read_timeout` время; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `grpc_read_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при чтении ответа gRPC-сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени gRPC-сервер ничего не передаст, соединение закрывается.
### grpc_send_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_send_timeout` время; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `grpc_send_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при передаче запроса gRPC-серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени gRPC-сервер не примет новых данных, соединение закрывается.
### grpc_set_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_set_header` поле значение; |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| По умолчанию | `grpc_set_header Content-Length $content_length;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет переопределять или добавлять поля заголовка запроса, [передаваемые](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass-request-headers) проксируемому серверу. В качестве значения можно использовать текст, переменные и их комбинации. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы grpc_set_header.
Если значение поля заголовка — пустая строка, то поле вообще не будет передаваться gRPC-серверу:
```nginx
grpc_set_header Accept-Encoding "";
```
### grpc_socket_keepalive
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_socket_keepalive` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `grpc_socket_keepalive off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Конфигурирует поведение "TCP keepalive" для исходящих соединений к проксируемому серверу.
| `""` | По умолчанию для сокета действуют настройки операционной системы. |
|--------|---------------------------------------------------------------------|
| `on` | для сокета включается параметр SO_KEEPALIVE |
### grpc_ssl_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_certificate` файл; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с сертификатом в формате PEM для аутентификации на gRPC SSL-сервере. В имени файла можно использовать переменные.
### grpc_ssl_certificate_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_certificate_cache` `off`;
`grpc_ssl_certificate_cache` `max=`N [`inactive=`time] [`valid=`time]; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| Значение по умолчанию | `grpc_ssl_certificate_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет кэш для хранения [SSL-сертификатов](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-ssl-certificate) и [секретных ключей](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-ssl-certificate-key), заданных через переменные.
Директива поддерживает следующие параметры:
- `max` — устанавливает максимальное количество элементов в кэше. При переполнении кэша
удаляются наименее недавно использованные (LRU) элементы.
- `inactive` — определяет время, после которого элемент будет удален, если
к нему не было обращений. Значение по умолчанию — 10 секунд.
- `valid` — определяет время, в течение которого элемент кэша считается
действительным и может использоваться повторно. Значение по умолчанию — 60 секунд. По истечении этого времени
сертификаты перезагружаются или проходят повторную проверку.
- `off` — отключает кэш.
Пример:
```nginx
grpc_ssl_certificate $grpc_ssl_server_name.crt;
grpc_ssl_certificate_key $grpc_ssl_server_name.key;
grpc_ssl_certificate_cache max=1000 inactive=20s valid=1m;
```
### grpc_ssl_certificate_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_certificate_key` файл; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с секретным ключом в формате PEM для аутентификации на gRPC SSL-сервере.
Вместо файла можно указать значение "engine:имя:id", которое загружает ключ с указанным id из OpenSSL engine с заданным именем.
Вместо файла можно указать значение "store:scheme:id", которое используется для загрузки ключа с указанным id и URI-схемой scheme, зарегистрированной в OpenSSL provider, например [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).
В имени файла можно использовать переменные.
### grpc_ssl_ciphers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_ciphers` шифры; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `grpc_ssl_ciphers DEFAULT;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Описывает разрешенные шифры для запросов к gRPC SSL-серверу. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL.
Список шифров зависит от установленной версии OpenSSL.
Полный список можно посмотреть с помощью команды `openssl ciphers`.
#### WARNING
Директива `grpc_ssl_ciphers` *не* настраивает шифры для TLS 1.3 при
использовании OpenSSL. Для настройки шифров TLS 1.3 в OpenSSL используйте
директиву [grpc_ssl_conf_command](#adc-grpc-ssl-conf-command), добавленную для расширенной
конфигурации SSL.
- В LibreSSL шифры TLS 1.3 *можно* настраивать с помощью
`grpc_ssl_ciphers`.
- В BoringSSL шифры TLS 1.3 настроить невозможно.
### grpc_ssl_conf_command
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_conf_command` имя значение; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает произвольные конфигурационные [команды](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) OpenSSL при установлении соединения с gRPC SSL-сервером.
#### NOTE
Директива поддерживается при использовании OpenSSL 1.0.2 и выше.
Чтобы настроить шифры TLS 1.3 в OpenSSL, используйте команду `ciphersuites`.
На одном уровне может быть указано несколько директив grpc_ssl_conf_command. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы grpc_ssl_conf_command.
#### WARNING
Следует учитывать, что изменение настроек OpenSSL напрямую может привести к неожиданному поведению.
### grpc_ssl_crl
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_crl` файл; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Указывает файл с отозванными сертификатами (CRL) в формате PEM, используемыми при [проверке](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-ssl-verify) сертификата gRPC SSL-сервера.
### grpc_ssl_name
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_name` имя; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `grpc_ssl_name `имя хоста` из grpc_pass;\` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет переопределить имя сервера, используемое при [проверке](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-ssl-verify) сертификата gRPC SSl-сервера, а также для [передачи его через SNI](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-ssl-server-name) при установлении соединения с gRPC SSL-сервером.
По умолчанию используется имя хоста из [grpc_pass](#adc-grpc-pass).
### grpc_ssl_password_file
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_password_file` файл; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с паролями от [секретных ключей](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-ssl-certificate-key), где каждый пароль указан на отдельной строке. Пароли применяются по очереди в момент загрузки ключа.
### grpc_ssl_protocols
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| По умолчанию | `grpc_ssl_protocols TLSv1.2 TLSv1.3;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает указанные протоколы для запросов к gRPC SSL-серверу.
### grpc_ssl_server_name
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_server_name` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `grpc_ssl_server_name off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает передачу имени сервера,
заданного директивой [grpc_ssl_name](#adc-grpc-ssl-name),
через расширение
[Server Name Indication](http://en.wikipedia.org/wiki/Server_Name_Indication)
протокола TLS
(SNI,
[RFC 6066](https://datatracker.ietf.org/doc/html/rfc6066.html))
при установлении соединения с SSL-сервером gRPC.
### grpc_ssl_session_reuse
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_session_reuse` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `grpc_ssl_session_reuse on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, использовать ли повторно SSL-сессии при работе с gRPC-сервером. Если в логах появляются ошибки "SSL3_GET_FINISHED:digest check failed", то можно попробовать выключить повторное использование сессий.
### grpc_ssl_trusted_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_trusted_certificate` файл; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с доверенными сертификатами CA в формате PEM, используемыми при [проверке](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-ssl-verify) сертификата gRPC SSL-сервера.
### grpc_ssl_verify
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_verify` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `grpc_ssl_verify off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает проверку сертификата gRPC SSL-сервера.
### grpc_ssl_verify_depth
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `grpc_ssl_verify_depth` число; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `grpc_ssl_verify_depth 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Устанавливает глубину проверки в цепочке сертификатов gRPC SSL-сервера.
# https://angie.software/adc/docs/load_balancer/reference/http/http_gunzip.md
# GunZIP
Фильтр, распаковывающий ответы с `Content-Encoding: gzip` для тех клиентов, которые не поддерживают метод сжатия "gzip". Модуль будет полезен, когда данные желательно хранить сжатыми для экономии места и сокращения затрат на ввод-вывод.
## Пример конфигурации
```nginx
location /storage/ {
gunzip on;
# ...
}
```
## Директивы
### gunzip
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gunzip` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию | `gunzip off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает распаковку ответов, сжатых методом gzip, для тех клиентов, которые его не поддерживают. Если разрешено, то для определения, поддерживает ли клиент gzip, также учитываются следующие директивы: [gzip_http_version](https://angie.software//adc/docs/load_balancer/reference/http/http_gzip.md#adc-gzip-http-version), [gzip_proxied](https://angie.software//adc/docs/load_balancer/reference/http/http_gzip.md#adc-gzip-proxied) и [gzip_disable](https://angie.software//adc/docs/load_balancer/reference/http/http_gzip.md#adc-gzip-disable). См. также директиву [gzip_vary](https://angie.software//adc/docs/load_balancer/reference/http/http_gzip.md#adc-gzip-vary).
### gunzip_buffers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gunzip_buffers` число размер; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `gunzip_buffers 32 4k | 16 8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число и размер буферов, в которые будет разжиматься ответ. По умолчанию размер одного буфера равен размеру страницы. В зависимости от платформы это или 4K, или 8K.
# https://angie.software/adc/docs/load_balancer/reference/http/http_gzip.md
# GZip
Фильтр, сжимающий ответ методом gzip, что позволяет уменьшить размер передаваемых данных в 2 и более раз.
#### WARNING
При использовании протокола SSL/TLS сжатые ответы могут быть подвержены атакам [BREACH](https://en.wikipedia.org/wiki/BREACH).
## Пример конфигурации
```nginx
gzip on;
gzip_min_length 1000;
gzip_proxied expired no-cache no-store private auth;
gzip_types text/plain application/xml;
```
Для записи в лог достигнутого коэффициента сжатия можно использовать переменную [$gzip_ratio](#adc-v-gzip-ratio).
## Директивы
### gzip
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `gzip off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Разрешает или запрещает сжатие ответа методом gzip.
### gzip_buffers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip_buffers` число размер; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `gzip_buffers 32 4k | 16 8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число и размер буферов, в которые будет сжиматься ответ. По умолчанию размер одного буфера равен размеру страницы. В зависимости от платформы это или 4K, или 8K.
### gzip_comp_level
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip_comp_level` степень; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `gzip_comp_level 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Устанавливает степень сжатия ответа методом gzip. Допустимые значения находятся в диапазоне от 1 до 9.
### gzip_disable
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip_disable` regex ...; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Запрещает сжатие ответа методом gzip для запросов с полями заголовка `User-Agent`, совпадающими с заданными регулярными выражениями.
Специальная маска `msie6` соответствует регулярному выражению "MSIE [4-6].", но работает быстрее. Из этой маски исключается "MSIE 6.0; ... SV1".
### gzip_http_version
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip_http_version` `1.0` | `1.1`; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `gzip_http_version 1.1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Устанавливает минимальную HTTP-версию запроса, необходимую для сжатия ответа.
### gzip_min_length
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip_min_length` длина; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `gzip_min_length 20;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Устанавливает минимальную длину ответа, который будет сжиматься методом gzip. Длина определяется только из поля `Content-Length` заголовка ответа.
### gzip_proxied
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip_proxied` `off` | `expired` | `no-cache` | `no-store` | `private` | `no_last_modified` | `no_etag` | `auth` | `any` ...; |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `gzip_proxied off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает сжатие ответа методом gzip для проксированных запросов в зависимости от запроса и ответа. То, что запрос проксированный, определяется на основании наличия поля `Via` в заголовке запроса. В директиве можно указать одновременно несколько параметров:
| `off` | запрещает сжатие для всех проксированных запросов, игнорируя остальные параметры; |
|--------------------|------------------------------------------------------------------------------------------------------|
| `expired` | разрешает сжатие, если в заголовке ответа есть поле `Expires` со значением, запрещающим кэширование; |
| `no-cache` | разрешает сжатие, если в заголовке ответа есть поле `Cache-Control` с параметром "no-cache"; |
| `no-store` | разрешает сжатие, если в заголовке ответа есть поле `Cache-Control` с параметром "no-store"; |
| `private` | разрешает сжатие, если в заголовке ответа есть поле `Cache-Control` с параметром "private"; |
| `no_last_modified` | разрешает сжатие, если в заголовке ответа нет поля `Last-Modified`; |
| `no_etag` | разрешает сжатие, если в заголовке ответа нет поля `ETag`; |
| `auth` | разрешает сжатие, если в заголовке запроса есть поле `Authorization`; |
| `any` | разрешает сжатие для всех проксированных запросов. |
### gzip_types
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip_types` mime-тип ...; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `gzip_types text/html;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает сжатие ответа методом gzip для указанных MIME-типов в дополнение к `text/html`. Специальное значение "\*" соответствует любому MIME-типу. Ответы с типом `text/html` сжимаются всегда.
### gzip_vary
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip_vary` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `gzip_vary off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает выдавать в ответе поле заголовка "Vary: Accept-Encoding", если активны директивы [gzip](#adc-gzip), [gzip_static](https://angie.software//adc/docs/load_balancer/reference/http/http_gzip_static.md#adc-gzip-static) или [gunzip](https://angie.software//adc/docs/load_balancer/reference/http/http_gunzip.md#adc-gunzip).
## Встроенные переменные
### `$gzip_ratio`
достигнутый коэффициент сжатия — отношение размера исходного ответа к размеру сжатого.
# https://angie.software/adc/docs/load_balancer/reference/http/http_gzip_static.md
# GZip Static
Позволяет отдавать вместо обычного файла предварительно сжатый файл с таким же именем и с расширением ".gz".
## Пример конфигурации
```nginx
gzip_static on;
gzip_proxied expired no-cache no-store private auth;
```
## Директивы
### gzip_static
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `gzip_static` `on` | `off` | `always`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `gzip_static off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает (`on`) или запрещает (`off`) проверку готового сжатого файла. При использовании также учитываются директивы [gzip_http_version](https://angie.software//adc/docs/load_balancer/reference/http/http_gzip.md#adc-gzip-http-version), [gzip_proxied](https://angie.software//adc/docs/load_balancer/reference/http/http_gzip.md#adc-gzip-proxied), [gzip_disable](https://angie.software//adc/docs/load_balancer/reference/http/http_gzip.md#adc-gzip-disable) и [gzip_vary](https://angie.software//adc/docs/load_balancer/reference/http/http_gzip.md#adc-gzip-vary).
Со значением `always` во всех случаях будет использоваться сжатый файл, без проверки поддержки на стороне клиента. Это полезно, если на диске все равно нет несжатых файлов, или используется модуль [GunZIP](https://angie.software//angie/docs/configuration/modules/http/http_gunzip.md#http-gunzip).
Сжимать файлы можно с помощью программы gzip или совместимой с ней. Желательно, чтобы дата и время модификации исходного и сжатого файлов совпадали.
# https://angie.software/adc/docs/load_balancer/reference/http/http_headers.md
# Headers
Позволяет выдавать поля заголовка `Expires` и `Cache-Control`, а также добавлять произвольные поля в заголовок ответа.
## Пример конфигурации
```nginx
expires 24h;
expires modified +24h;
expires @24h;
expires 0;
expires -1;
expires epoch;
expires $expires;
add_header Cache-Control private;
```
## Директивы
### add_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `add_header` имя значение [`always`]; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Добавляет указанное поле в заголовок ответа при условии, что код ответа равен 200, 201 (1.3.10), 204, 206, 301, 302, 303, 304, 307 или 308. В значении параметра можно использовать переменные.
Директив add_header может быть несколько. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы add_header.
Если указан параметр `always`, то поле заголовка будет добавлено независимо от кода ответа.
### add_trailer
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `add_trailer` имя значение [`always`]; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Добавляет указанное поле в конец ответа при условии, что код ответа равен 200, 201, 206, 301, 302, 303, 307 или 308. В значении можно использовать переменные.
Директив add_trailer может быть несколько. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы add_trailer.
Если указан параметр `always`, то указанное поле будет добавлено независимо от кода ответа.
### expires
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `expires` [`modified`] время;
`expires` `epoch` | `max` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| По умолчанию | `expires off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Разрешает или запрещает добавлять или менять поля `Expires` и `Cache-Control` в заголовке ответа при условии, что код ответа равен 200, 201, 204, 206, 301, 302, 303, 304, 307 или 308. В качестве параметра можно задать положительное или отрицательное [время](https://angie.software//angie/docs/configuration/configfile.md#syntax).
Время в поле `Expires` получается как сумма текущего времени и времени, заданного в директиве. Если используется параметр `modified`, то время получается как сумма времени модификации файла и времени, заданного в директиве.
Кроме того, с помощью префикса "@" можно задать время суток:
```nginx
expires @15h30m;
```
Содержимое поля `Cache-Control` зависит от знака заданного времени:
* отрицательное время — "Cache-Control: no-cache".
* положительное или равное нулю время — "Cache-Control: max-age=\`t\`", где t это время в секундах, заданное в директиве.
| `epoch` | задает время "Thu, 01 Jan 1970 00:00:01 GMT" (1 января 1970 00:00:01 GMT) для поля `Expires` и "no-cache" для поля `Cache-Control`. |
|-----------|---------------------------------------------------------------------------------------------------------------------------------------|
| `max` | задает время "Thu, 31 Dec 2037 23:55:55 GMT" (31 декабря 2037 23:55:55 GMT) для поля `Expires` и 10 лет для поля `Cache-Control`. |
| `off` | запрещает добавлять или менять поля `Expires` и `Cache-Control` в заголовке ответа. |
В значении последнего параметра можно использовать переменные:
```nginx
map $sent_http_content_type $expires {
default off;
application/pdf 42d;
~image/ max;
}
expires $expires;
```
# https://angie.software/adc/docs/load_balancer/reference/http/http_index.md
# Index
Обслуживает запросы, оканчивающиеся косой чертой (`/`). Такие запросы также могут обслуживаться модулями [AutoIndex](https://angie.software//angie/docs/configuration/modules/http/http_autoindex.md#http-autoindex) и [Random Index](https://angie.software//angie/docs/configuration/modules/http/http_random_index.md#http-random-index).
## Пример конфигурации
```nginx
location / {
index index.$geo.html index.html;
}
```
## Директивы
### index
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `index` файл ...; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | `index index.html;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет файлы, которые будут использоваться в качестве индекса. В имени файла можно использовать переменные. Наличие файлов проверяется в порядке их перечисления. В конце списка может стоять файл с абсолютным путем. Пример:
```nginx
index index.$geo.html index.0.html /index.html;
```
Необходимо иметь в виду, что при использовании индексного файла делается внутреннее перенаправление и запрос может быть обработан уже в другом `location`. Например, в такой конфигурации:
```nginx
location = / {
index index.html;
}
location / {
# ...
}
```
запрос `"/"` будет фактически обработан во втором `location` как "/index.html".
# https://angie.software/adc/docs/load_balancer/reference/http/http_limit_conn.md
# Limit Conn
Позволяет ограничить число соединений по заданному ключу, в частности, число соединений с одного IP-адреса.
Учитываются не все соединения, а лишь те, в которых имеются запросы, обрабатываемые сервером, и заголовок запроса уже прочитан.
## Пример конфигурации
```nginx
http {
limit_conn_zone $binary_remote_addr zone=addr:10m;
...
server {
...
location /download/ {
limit_conn addr 1;
}
```
## Директивы
### limit_conn
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_conn` зона число; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает зону разделяемой памяти и максимально допустимое число соединений для одного значения ключа. При превышении этого числа в ответ на запрос сервер вернет [ошибку](https://angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#limit-conn-status). Например, директивы
```nginx
limit_conn_zone $binary_remote_addr zone=addr:10m;
server {
location /download/ {
limit_conn addr 1;
}
```
разрешают одновременно обрабатывать не более одного соединения с одного IP-адреса.
#### NOTE
В HTTP/2 и HTTP/3 каждый параллельный запрос считается отдельным соединением.
Директив limit_conn может быть несколько. Например, следующая конфигурация ограничивает число соединений с сервером с одного клиентского IP-адреса и в то же время ограничивает общее число соединений с виртуальным сервером:
```nginx
limit_conn_zone $binary_remote_addr zone=perip:10m;
limit_conn_zone $server_name zone=perserver:10m;
server {
...
limit_conn perip 10;
limit_conn perserver 100;
}
```
Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы limit_conn.
### limit_conn_dry_run
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_conn_dry_run` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `limit_conn_dry_run off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Включает режим пробного запуска. В данном режиме число соединений не ограничивается, однако в [зоне разделяемой памяти](https://angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#limit-conn-zone) текущее число избыточных соединений учитывается как обычно.
### limit_conn_log_level
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_conn_log_level` `info` | `notice` | `warn` | `error`; |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------|
| По умолчанию | `limit_conn_log_level error;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает желаемый уровень записи в лог случаев ограничения числа соединений.
### limit_conn_status
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_conn_status` код; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `limit_conn_status 503;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет переопределить код ответа, используемый при отклонении запросов.
### limit_conn_zone
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_conn_zone` ключ zone = название:размер; |
|------------------------------------------------------------------------------------------|--------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает параметры зоны разделяемой памяти, которая хранит состояние для разных значений ключа. Состояние в частности содержит текущее число соединений. В качестве ключа можно использовать текст, переменные и их комбинации. Запросы с пустым значением ключа не учитываются.
Пример использования:
```nginx
limit_conn_zone $binary_remote_addr zone=addr:10m;
```
Здесь в качестве ключа используется IP-адрес клиента. Обратите внимание, что вместо переменной `$remote_addr` использована переменная `$binary_remote_addr`.
Длина значения переменной `$remote_addr` может колебаться от 7 до 15 байт, при этом размер хранимого состояния составляет либо 32, либо 64 байта на 32-битных платформах и всегда 64 байта на 64-битных.
Длина значения переменной `$binary_remote_addr` всегда равна 4 байтам для IPv4-адресов или 16 байтам для IPv6-адресов. При этом размер состояния всегда равен 32 или 64 байтам на 32-битных платформах и 64 байтам на 64-битных.
В зоне размером 1 мегабайт может разместиться около 32 тысяч состояний размером 32 байта или 16 тысяч состояний размером 64 байта. При переполнении зоны в ответ на последующие запросы сервер будет возвращать [ошибку](https://angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#limit-conn-status).
## Встроенные переменные
### `$limit_conn_status`
хранит результат ограничения числа соединений: PASSED, REJECTED или REJECTED_DRY_RUN
# https://angie.software/adc/docs/load_balancer/reference/http/http_limit_req.md
# Limit Req
Позволяет ограничить скорость обработки запросов по заданному ключу или, как частный случай, скорость обработки запросов, поступающих с одного IP-адреса. Ограничение обеспечивается с помощью метода "leaky bucket".
## Пример конфигурации
```nginx
http {
limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
...
server {
...
location /search/ {
limit_req zone=one burst=5;
}
```
## Директивы
### limit_req
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_req` `zone=`название [`burst=`число] [nodelay | `delay=`число]; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает зону разделяемой памяти (`zone`) и максимальный размер всплеска запросов (`burst`). Если скорость поступления запросов превышает описанную в зоне, то их обработка задерживается так, чтобы запросы обрабатывались с заданной скоростью. Избыточные запросы задерживаются до тех пор, пока их число не превысит максимальный размер всплеска. При превышении запрос завершается с ошибкой. По умолчанию максимальный размер всплеска равен нулю. Например, директивы
```nginx
limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
server {
location /search/ {
limit_req zone=one burst=5;
}
```
позволяют в среднем не более 1 запроса в секунду со всплесками не более 5 запросов.
Если же избыточные запросы в пределах лимита всплесков задерживать не требуется, то следует использовать параметр `nodelay`:
```nginx
limit_req zone=one burst=5 nodelay;
```
Параметр `delay` задает лимит, по достижении которого избыточные запросы задерживаются. Значение по умолчанию равно нулю и означает, что задерживаются все избыточные запросы.
Директив `limit_req` может быть несколько. Например, следующая конфигурация ограничивает скорость обработки запросов, поступающих с одного IP-адреса, и в то же время ограничивает скорость обработки запросов одним виртуальным сервером:
```nginx
limit_req_zone $binary_remote_addr zone=perip:10m rate=1r/s;
limit_req_zone $server_name zone=perserver:10m rate=10r/s;
server {
...
limit_req zone=perip burst=5 nodelay;
limit_req zone=perserver burst=10;
}
```
Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы `limit_req`.
### limit_req_dry_run
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_req_dry_run` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `limit_req_dry_run off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Включает режим пробного запуска. В данном режиме скорость обработки запросов не ограничивается, однако в [зоне разделяемой памяти](https://angie.software//angie/docs/configuration/modules/http/http_limit_req.md#limit-req-zone) текущее число избыточных запросов учитывается как обычно.
### limit_req_log_level
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_req_log_level` `info` | `notice` | `warn` | `error`; |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------|
| По умолчанию | `limit_req_log_level error;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает желаемый уровень записи в лог случаев отказа в обработке запросов при превышении скорости и случаев задержек при обработке запроса. Задержки записываются в лог с уровнем на единицу меньшим, чем отказы, например, если указано `limit_req_log_level notice;`, то задержки будут записываться в лог на уровне `info`.
### limit_req_status
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_req_status` код; |
|------------------------------------------------------------------------------------------|---------------------------|
| По умолчанию | `limit_req_status 503;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет переопределить код ответа, используемый при отклонении запросов.
### limit_req_zone
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_req_zone` ключ `zone=`название:размер `rate=`скорость; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает параметры зоны разделяемой памяти, которая хранит состояние для разных значений ключа. Состояние в частности хранит текущее число избыточных запросов. В качестве ключа можно использовать текст, переменные и их комбинации. Запросы с пустым значением ключа не учитываются.
Пример использования:
```nginx
limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
```
В данном случае состояния хранятся в зоне `one` размером 10 мегабайт, и средняя скорость обработки запросов для этой зоны не может превышать 1 запроса в секунду.
В качестве ключа используется IP-адрес клиента. Обратите внимание, что вместо переменной `$remote_addr` используется переменная `$binary_remote_addr`.
Длина значения переменной `$binary_remote_addr` всегда равна 4 байтам для IPv4-адресов или 16 байтам для IPv6-адресов. При этом размер состояния всегда равен 64 байтам на 32-битных платформах и 128 байтам на 64-битных платформах.
В зоне размером 1 мегабайт может разместиться около 16 тысяч состояний размером 64 байта или около 8 тысяч состояний размером 128 байт.
При переполнении зоны удаляется наименее востребованное состояние. Если и это не позволяет создать новое состояние, запрос завершается с [ошибкой](https://angie.software//angie/docs/configuration/modules/http/http_limit_req.md#limit-req-status).
Скорость `rate` задается в запросах в секунду (r/s). Если же нужна скорость меньше одного запроса в секунду, то она задается в запросах в минуту (r/m), например, ползапроса в секунду — это 30r/m.
## Встроенные переменные
### `$limit_req_status`
хранит результат ограничения скорости поступления запросов: `PASSED`, `DELAYED`, `REJECTED`, `DELAYED_DRY_RUN` или `REJECTED_DRY_RUN`
# https://angie.software/adc/docs/load_balancer/reference/http/http_log.md
# Log
Модуль записывает логи запросов в указанном формате.
Логи записываются в контексте `location`, где заканчивается обработка. Это может быть `location`, отличный от первоначального, если в процессе обработки запроса происходит [внутреннее перенаправление](https://angie.software//angie/docs/configuration/modules/http/index.md#internal).
## Пример конфигурации
```nginx
log_format compression '$remote_addr - $remote_user [$time_local] '
'"$request" $status $bytes_sent '
'"$http_referer" "$http_user_agent" "$gzip_ratio"';
access_log /spool/logs/angie-access.log compression buffer=32k;
```
## Директивы
### access_log
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `access_log` путь [формат [`buffer=`размер] [`gzip=`степень]] [`flush=`время] [`if=`условие]];
`access_log` `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `access_log logs/access.log combined;`
(путь зависит от [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-log-path`) |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location, limit_except |
Задает путь, формат и настройки буферизованной записи в лог. На одном уровне конфигурации может использоваться несколько логов. Запись в [syslog](https://angie.software//angie/docs/configuration/processing.md#syslog-logging) настраивается указанием префикса "syslog:" в первом параметре. Специальное значение off отменяет все директивы access_log для текущего уровня. Если формат не указан, то используется предопределенный формат "combined".
Если задан размер буфера с помощью параметра `buffer` или указан параметр `gzip`, то запись будет буферизованной.
#### WARNING
Размер буфера должен быть не больше размера атомарной записи в дисковый файл. Для FreeBSD этот размер неограничен.
При включенной буферизации данные записываются в файл:
* если очередная строка лога не помещается в буфер;
* если данные в буфере находятся дольше интервала времени, заданного параметром flush;
* при [переоткрытии лог-файла](https://angie.software//angie/docs/configuration/runtime.md#log-rotation) или завершении рабочего процесса.
Если задан параметр `gzip`, то буфер будет сжиматься перед записью в файл. Степень сжатия может быть задана в диапазоне от 1 (быстрее, но хуже сжатие) до 9 (медленнее, но лучше сжатие). По умолчанию используются буфер размером 64К байт и степень сжатия 1. Данные сжимаются атомарными блоками, и в любой момент времени лог-файл может быть распакован или прочитан с помощью утилиты **zcat**.
Пример:
```nginx
access_log /path/to/log.gz combined gzip flush=5m;
```
#### NOTE
Для поддержки gzip-сжатия логов Angie должен быть собран с библиотекой zlib.
В пути файла можно использовать переменные, но такие логи имеют некоторые ограничения:
* [пользователь](https://angie.software//angie/docs/configuration/modules/core.md#user), с правами которого работают рабочие процессы, должен иметь права на создание файлов в каталоге с такими логами;
* не работает буферизация;
* файл открывается для каждой записи в лог и сразу же после записи закрывается. Следует однако иметь в виду, что поскольку дескрипторы часто используемых файлов могут храниться в кэше, то при ротации логов в течение времени, заданного параметром valid директивы [open_log_file_cache](#adc-open-log-file-cache), запись может продолжаться в старый файл.
* при каждой записи в лог проверяется существование корневого каталога для запроса — если этот каталог не существует, то лог не создается. Поэтому [root](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-root) и [access_log](#adc-access-log) нужно описывать на одном уровне конфигурации:
```nginx
server {
root /spool/vhost/data/$host;
access_log /spool/vhost/logs/$host;
...
```
Параметр `if` включает условную запись в лог. Запрос не будет записываться в лог, если результатом вычисления условия является `"0"` или пустая строка. В следующем примере запросы с кодами ответа 2xx и 3xx не будут записываться в лог:
```nginx
map $status $loggable {
~^[23] 0;
default 1;
}
access_log /path/to/access.log combined if=$loggable;
```
### log_format
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `log_format` имя [`escape`= `default` | `json` | `none` ] строка ...; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
| По умолчанию | `log_format combined "...";` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает формат лога.
Параметр `escape` позволяет задать экранирование символов `json` или
`default` в переменных, по умолчанию используется `default`.
Значение `none` отключает экранирование символов.
При использовании `default` символы """, "\\", а также символы со
значениями меньше 32 или больше 126 экранируются как "\\xXX". Если значение
переменной не найдено, то в качестве значения в лог будет записываться дефис
"-".
При использовании `json` экранируются все символы, недопустимые в JSON
строках: символы """ и "\\" экранируются как "\\"" и "\\\\", символы со
значениями меньше 32 экранируются как "\\n", "\\r", "\\t", "\\b", "\\f" или
"\\u00XX".
Строки заголовка, переданные клиенту, начинаются с префикса `sent_http_`,
например, `$sent_http_content_range`.
В конфигурации всегда существует предопределенный формат `combined`:
```nginx
log_format combined '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent"';
```
### open_log_file_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `open_log_file_cache` `max=`N [`inactive=`время] [`min_uses=`N] [`valid=`время];
`open_log_file_cache` `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `open_log_file_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает кэш, в котором хранятся дескрипторы файлов часто используемых логов, имена которых заданы с использованием переменных. Параметры:
| `max` | Задает максимальное число дескрипторов в кэше; при переполнении кэша наименее востребованные (LRU) дескрипторы закрываются. |
|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `inactive` | Задает время, после которого кэшированный дескриптор закрывается, если к нему не было обращений в течение этого времени.
По умолчанию — 10 секунд. |
| `min_uses` | Задает минимальное число использований файла в течение времени, заданного параметром `inactive`, после которого дескриптор файла будет оставаться открытым в кэше.
По умолчанию — 1. |
| `valid` | Указыает, через какое время нужно проверять, что файл еще существует под тем же именем.
По умолчанию — 60 секунд. |
| `off` | Запрещает кэширование. |
Пример использования:
```nginx
open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;
```
# https://angie.software/adc/docs/load_balancer/reference/http/http_map.md
# Map
Создает переменные, значения которых зависят от значений других переменных.
## Пример конфигурации
```nginx
map $http_host $name {
hostnames;
default 0;
example.com 1;
*.example.com 1;
example.org 2;
*.example.org 2;
.example.net 3;
wap.* 4;
}
map $http_user_agent $mobile {
default 0;
"~Opera Mini" 1;
}
```
## Директивы
### map
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `map` строка $переменная { ... } |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Создает новую переменную.
Ее значение зависит от первого параметра, заданного строкой с переменными,
например:
```nginx
set $var1 "foo";
set $var2 "bar";
map $var1$var2 $new_variable {
default "foobar_value";
}
```
Здесь переменная `$new_variable` будет иметь значение,
составленное из двух переменных `$var1` и `$var2`,
или значение по умолчанию, если эти переменные не определены.
#### NOTE
Поскольку переменные вычисляются только в момент использования, само по себе наличие даже большого числа объявлений переменных "map" не влечет за собой никаких дополнительных расходов на обработку запросов.
Параметры внутри блока `map` задают соответствие между исходными и результирующими значениями.
Исходные значения задаются строками или регулярными выражениями.
Строки проверяются без учета регистра.
Перед регулярным выражением ставится символ `~`, если при сравнении
следует учитывать регистр символов, либо символы `~*`, если регистр
символов учитывать не нужно. Регулярное выражение может содержать именованные и
позиционные группы захвата, которые могут затем использоваться в других
директивах совместно с результирующей переменной.
Если исходное значение совпадает с именем одного из специальных параметров,
описанных ниже, перед ним следует поставить символ `\`.
В качестве результирующего значения можно указать текст, переменную и их комбинации.
Также поддерживаются следующие специальные параметры:
| `default` значение | задает результирующее значение, если исходное значение не совпадает ни с одним из перечисленных. Если параметр default не указан, результирующим значением по умолчанию будет пустая строка. |
|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `hostnames` | указывает, что в качестве исходных значений можно использовать маску для первой или последней части имени хоста. Этот параметр следует указывать перед списком значений. |
Например,
```nginx
*.example.com 1;
example.* 1;
```
Вместо двух записей
```nginx
example.com 1;
*.example.com 1;
```
можно использовать одну:
```nginx
.example.com 1;
```
| `include` файл | включает файл со значениями. Включений может быть несколько. |
|------------------|----------------------------------------------------------------|
| `volatile` | указывает, что переменная не кэшируется. |
Если исходному значению соответствует несколько из указанных вариантов, например, одновременно подходят и маска, и регулярное выражение, будет выбран первый подходящий вариант в следующем порядке приоритета:
1. Строковое значение без маски.
2. Самое длинное строковое значение с маской в начале, например "`*.example.com`".
3. Самое длинное строковое значение с маской в конце, например "`mail.*`".
4. Первое подходящее регулярное выражение (в порядке следования в конфигурационном файле).
5. Значение по умолчанию (default).
### map_hash_bucket_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `map_hash_bucket_size` размер; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `map_hash_bucket_size 32|64|128;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает размер корзины в хэш-таблицах для переменных [map](#adc-map). Значение по умолчанию зависит от размера строки кэша процессора. Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
### map_hash_max_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `map_hash_max_size` размер; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `map_hash_max_size 2048;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает максимальный размер хэш-таблиц для переменных [map](#adc-map). Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
# https://angie.software/adc/docs/load_balancer/reference/http/http_memcached.md
# Memcached
Позволяет получать ответ из сервера memcached. Ключ задается в переменной [$memcached_key](#adc-v-memcached-key). Ответ в memcached должен быть предварительно помещен внешним по отношению к Angie способом.
## Пример конфигурации
```nginx
server {
location / {
set $memcached_key "$uri?$args";
memcached_pass host:11211;
error_page 404 502 504 = @fallback;
}
location @fallback {
proxy_pass http://backend;
}
}
```
## Директивы
### memcached_bind
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_bind` адрес [`transparent`] | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает локальный IP-адрес с необязательным портом, который будет использоваться в исходящих соединениях с сервером memcached. В значении параметра допустимо использование переменных. Специальное значение `off` отменяет действие унаследованной с предыдущего уровня конфигурации директивы memcached_bind, позволяя системе самостоятельно выбирать локальный IP-адрес и порт.
Параметр `transparent` позволяет задать нелокальный IP-aдрес, который будет использоваться в исходящих соединениях с проксируемым сервером, например, реальный IP-адрес клиента:
```nginx
memcached_bind $remote_addr transparent;
```
Для работы параметра обычно требуется запустить рабочие процессы Angie с привилегиями [суперпользователя](https://angie.software//angie/docs/configuration/modules/core.md#user). В Linux это не требуется, так как если указан параметр transparent, то рабочие процессы наследуют capability CAP_NET_RAW из главного процесса.
#### NOTE
Необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с серверa memcached.
### memcached_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_buffer_size` размер; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `memcached_buffer_size 4k|8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает размер буфера, в который будет читаться первая часть ответа, получаемого от сервера memcached. Ответ синхронно передается клиенту сразу же по мере его поступления.
### memcached_connect_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_connect_timeout` время; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `memcached_connect_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут для установления соединения с сервером memcached. Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.
### memcached_gzip_flag
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_gzip_flag` флаг; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Включает проверку указанного флага в ответе сервера memcached и установку поля `Content-Encoding` заголовка ответа в "gzip", если этот флаг установлен.
### memcached_next_upstream
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_next_upstream` `error` | `timeout` | `invalid_response` | `not_found` | `off` ...; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|
| По умолчанию | `memcached_next_upstream error timeout;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, в каких случаях запрос будет передан следующему в группе [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) серверу:
| `error` | произошла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
|--------------------|-------------------------------------------------------------------------------------------------------------|
| `timeout` | произошел таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
| `invalid_response` | сервер вернул пустой или неверный ответ; |
| `not_found` | сервер не нашел ответ; |
| `off` | запрещает передачу запроса следующему серверу. |
#### NOTE
Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту еще ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа клиенту, то действие директивы на такой запрос не распространяется.
Директива также определяет, что считается [неудачной попыткой](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) работы с сервером.
| `error`, `timeout`, `invalid_response` | Всегда считаются неудачными попытками, даже если они не указаны в директиве. |
|------------------------------------------|--------------------------------------------------------------------------------|
| `not_found` | Никогда не считается неудачными попытками. |
Передача запроса следующему серверу может быть ограничена по [количеству попыток](https://angie.software//angie/docs/configuration/modules/http/http_memcached.md#memcached-next-upstream-tries) и по [времени](https://angie.software//angie/docs/configuration/modules/http/http_memcached.md#memcached-next-upstream-timeout).
### memcached_next_upstream_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_next_upstream_timeout` время; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `memcached_next_upstream_timeout 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает время, в течение которого возможна передача запроса [следующему](https://angie.software//angie/docs/configuration/modules/http/http_memcached.md#memcached-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### memcached_next_upstream_tries
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_next_upstream_tries` число; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `memcached_next_upstream_tries 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает число допустимых попыток для передачи запроса [следующему](https://angie.software//angie/docs/configuration/modules/http/http_memcached.md#memcached-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### memcached_pass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_pass` адрес; |
|------------------------------------------------------------------------------------------|---------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location, if в location |
Задает адрес сервера memcached. Адрес может быть указан в виде доменного имени или IP-адреса, и порта:
```nginx
memcached_pass localhost:11211;
```
или в виде пути UNIX-сокета:
```nginx
memcached_pass unix:/tmp/memcached.socket;
```
Если доменному имени соответствует несколько адресов, то все они будут использоваться по очереди (round-robin). Кроме того, в качестве адреса можно указать [группу серверов](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).
#### NOTE
Если `memcached_pass` стоит в `location` с косой чертой в конце префикса
(например, `location /name/`),
и при этом в директиве [auto_redirect](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-auto-redirect) указано `default`,
запросы без косой черты в конце будут перенаправляться (`/name -> /name/`).
### memcached_read_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_read_timeout` время; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `memcached_read_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при чтении ответа сервера memcached. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени сервер memcached ничего не передаст, соединение закрывается.
### memcached_send_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_send_timeout` время; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `memcached_send_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при передаче запроса серверу memcached. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени сервер memcached не примет новых данных, соединение закрывается.
### memcached_socket_keepalive
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `memcached_socket_keepalive` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | `memcached_socket_keepalive off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Конфигурирует поведение "TCP keepalive" для исходящих соединений к проксируемому серверу.
| `""` | По умолчанию для сокета действуют настройки операционной системы. |
|--------|---------------------------------------------------------------------|
| `on` | для сокета включается параметр SO_KEEPALIVE |
## Встроенные переменные
### `$memcached_key`
Задает ключ для получения ответа из сервера memcached.
# https://angie.software/adc/docs/load_balancer/reference/http/http_metric.md
# Metric
Модуль `ngx_http_metric_module` позволяет создавать вычисляемые в реальном времени
произвольные метрики. Значения таких метрик сохраняются в разделяемой памяти
и отображаются в реальном времени в ветке API `/status/http/metric_zones/`.
Поддерживаются различные типы агрегации данных (счетчики, гистограммы, скользящие средние и др.)
с группировкой по произвольным ключам.
## Пример конфигурации
Подсчет запросов к API:
```nginx
http {
metric_zone api_requests:1m count;
server {
listen 80;
location /api/ {
allow 127.0.0.1;
deny all;
api /status/;
metric api_requests $http_user_agent on=request;
}
}
}
```
Если с такой конфигурацией выполнить запрос на `/api/`:
```console
$ curl 127.0.0.1/api/ --user-agent "Firefox"
```
В реальном времени происходит обновление метрики `api_requests`:
```json
{
"http": {
"metric_zones": {
"api_requests": {
"discarded": 0,
"metrics": {
"Firefox": 1
}
}
}
}
}
```
## Директивы
### metric_zone
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `metric_zone` название:размер [`expire`=`on`| `off`] [`discard_key`=`название`] режим [параметры]; |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Создает зону разделяемой памяти указанного размера с именем название,
в которой хранятся метрики. Имя зоны является узлом в ветке
`/status/http/metric_zones/`.
Параметры:
- `expire=` — поведение при переполнении зоны:
- Если `on`, самые старые метрики по времени обновления отбрасываются,
освобождая память под поступающие;
- Если `off` (по умолчанию) — отбрасываются поступающие метрики,
сохраняя информацию об установленных.
- `discard_key=<название>` — задает метрику с ключом название,
в которой сохраняются значения отброшенных метрик. По умолчанию такая метрика
не создается. Зарезервированный ключ нельзя обновлять вручную.
- режим — алгоритм обработки значений (см. раздел [Режимы работы](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-modes));
- параметры — дополнительная настройка выбранного режима
(например, `factor` для `average exp`).
Пример использования:
```nginx
metric_zone request_time:1m max;
```
В API дереве шаблон зоны разделяемой памяти выглядит следующим образом:
```json
{
"discarded": 0,
"metrics": {
"ключ1": 123,
"ключ2": 10.5,
}
}
```
| `discarded` | Число; количество отброшенных метрик в зоне разделяемой памяти |
|---------------|---------------------------------------------------------------------------------|
| `metrics` | Объект; его члены — метрики с установленными ключами и подсчитанными значениями |
#### NOTE
В зоне размером 1 мегабайт при размере ключа 39 байт и с одним режимом
метрики может разместиться около 8 тысяч записей с уникальным ключом.
### metric_complex_zone
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `metric_complex_zone` название:размер [`expire`=`on`| `off`] [`discard_key`=`название`] { ... } |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Определяет составную метрику — набор метрик с независимыми режимами.
Каждая строка в теле блока задает название подметрики, режим
и необязательные параметры режима.
Пример использования:
```nginx
metric_complex_zone requests:1m expire=on discard_key="old" {
# название подметрики режим работы параметры
min_time min;
avg_time average exp factor=60;
max_time max;
total count;
}
```
В API дереве шаблон такой составной метрики выглядит следующим образом:
```json
{
"discarded": 3,
"metrics": {
"ключ1": {
"min_time": 20,
"avg_time": 50,
"max_time": 80,
"total": 2
},
"old": {
"min_time": 3,
"avg_time": 40,
"max_time": 152,
"total": 80
}
}
}
```
| `discarded` | Число; количество отброшенных метрик в зоне разделяемой памяти |
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| `metrics` | Объект; его члены — составные метрики с установленными ключами. Они представляют собой объекты, содержащие набор подметрик с подсчитанными значениями |
### metric
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `metric` название ключ=значение [`on`=`request`| `response`| `end`]; |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Подсчитывает значение метрики с указанным названием зоны разделяемой памяти.
Параметры:
- ключ — произвольная строка (часто переменная), по которой группируются
значения. Максимальная длина — 255 байт. Если ключ длиннее, он будет
ограничен размером 255 байт и дополнен `...` многоточием;
- значение — число (может быть переменной), обрабатываемое выбранным режимом.
Если пропущено, считается `0`. Если параметр невозможно преобразовать
в число, считается `1`;
- `on` — необязательный параметр, указывающий в какой момент происходит
подсчет метрики:
- Если `on=request`, подсчет происходит при получении запроса;
- Если `on=response`, подсчет происходит при подготовке ответа;
- Если `on=end` (по умолчанию), подсчет происходит после отправки ответа.
#### NOTE
В случае внутреннего перенаправления, метрики на стадии `on=request`
посчитаются в исходном `location`. При этом метрики
`on=response` и `on=end` будут подсчитаны уже в новом
`location`.
Пример использования:
```nginx
metric requests $http_user_agent=$request_time;
```
#### NOTE
Метрики с пустым ключом или неправильной парой `ключ=значение`
не учитываются. Пропущенное значение учитывается как `0`:
```nginx
metric foo $bar; # Вместо $bar=0
```
Что полезно, например, для режима `count`, который игнорирует
числовое значение и реагирует на факт обновления метрики.
#### NOTE
Важно помнить, что переменные вычисляются в разных фазах. Например,
невозможно использовать `$bytes_sent` (количество отправленных байт клиенту)
при `on=request` (при получении запроса).
## Режимы работы
Список доступных режимов работы метрик:
* `count` — счетчик обращений;
* `gauge` — стрелка (инкремент/декремент);
* `last` — последнее поступившее значение;
* `min` — минимальное значение;
* `max` — максимальное значение;
* `average exp` — скользящее среднее (параметр `factor`);
* `average mean` — среднее за окно (параметры `window` и `count`);
* `histogram` — распределение по "бакетам" (перечень пороговых значений).
### count
Счетчик увеличивает свое значение на `1` при каждом обновлении метрики.
Значение по умолчанию — `0`.
#### NOTE
Любое обновление метрики (с любым значением) монотонно увеличивает
счетчик на `1`.
Примеры:
```nginx
metric_zone count:1m count;
# В качесте составной метрики:
#
# metric_complex_zone count:1m {
# some_metric_name count;
# }
server {
listen 80;
location /metric/ {
metric count KEY;
}
location ~ ^/metric/set/(.+)$ {
metric count KEY=$1;
}
location /api/ {
api /status/http/metric_zones/count/metrics/;
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/
$ curl 127.0.0.1/metric/set/1
$ curl 127.0.0.1/metric/set/23
$ curl 127.0.0.1/metric/set/-32
```
Ожидаемое значение метрики в API:
```json
{
"KEY": 4
}
```
### gauge
Счетчик увеличивает или уменьшает свое значение в зависимости
от знака переданного числа. При положительном — увеличивает счетчик.
При отрицательном — уменьшает. Переданное значение `0` не изменяет счетчик.
Значение по умолчанию — `0`.
Примеры:
```nginx
metric_zone gauge:1m gauge;
# В качесте составной метрики:
#
# metric_complex_zone gauge:1m {
# some_metric_name gauge;
# }
server {
listen 80;
location /metric/ {
metric gauge KEY;
}
location ~ ^/metric/set/(.+)$ {
metric gauge KEY=$1;
}
location /api/ {
api /status/http/metric_zones/gauge/metrics/;
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/
```
Ожидаемое значение метрики в API:
```json
{
"KEY": 0
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/set/5
$ curl 127.0.0.1/metric/set/-5
$ curl 127.0.0.1/metric/set/8
```
Ожидаемое значение метрики в API:
```json
{
"KEY": 8
}
```
### last
Хранит последнее полученное значение без какой-либо агрегации.
Если значение опущено, используется `0`.
Примеры:
```nginx
metric_zone last:1m last;
# В качесте составной метрики:
#
# metric_complex_zone last:1m {
# some_metric_name last;
# }
server {
listen 80;
location /metric/ {
metric last KEY;
}
location ~ ^/metric/set/(.+)$ {
metric last KEY=$1;
}
location /api/ {
api /status/http/metric_zones/last/metrics/;
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/
```
Ожидаемое значение метрики в API:
```json
{
"KEY": 0
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/set/8000
$ curl 127.0.0.1/metric/set/37
$ curl 127.0.0.1/metric/set/-3.5
```
Ожидаемое значение метрики в API:
```json
{
"KEY": -3.5
}
```
### min
Сохраняет минимальное из двух значений — уже сохраненного и нового.
Примеры:
```nginx
metric_zone min:1m min;
# В качесте составной метрики:
#
# metric_complex_zone min:1m {
# some_metric_name min;
# }
server {
listen 80;
location /metric/ {
metric min KEY;
}
location ~ ^/metric/set/(.+)$ {
metric min KEY=$1;
}
location /api/ {
api /status/http/metric_zones/min/metrics/;
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/set/42.999
$ curl 127.0.0.1/metric/set/-512
$ curl 127.0.0.1/metric/set/1
$ curl 127.0.0.1/metric/
```
Ожидаемое значение метрики в API:
```json
{
"KEY": -512
}
```
### max
Сохраняет наибольшее из двух значений — уже сохраненного и нового.
Примеры:
```nginx
metric_zone max:1m max;
# В качесте составной метрики:
#
# metric_complex_zone max:1m {
# some_metric_name max;
# }
server {
listen 80;
location /metric/ {
metric max KEY;
}
location ~ ^/metric/set/(.+)$ {
metric max KEY=$1;
}
location /api/ {
api /status/http/metric_zones/max/metrics/;
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/set/42.999
$ curl 127.0.0.1/metric/set/-512
$ curl 127.0.0.1/metric/set/1
$ curl 127.0.0.1/metric/
```
Ожидаемое значение метрики в API:
```json
{
"KEY": 42.999
}
```
### average exp
Вычисляет среднее значение по алгоритму
[экспоненциального сглаживания](https://en.wikipedia.org/wiki/Exponential_smoothing).
Принимает необязательный параметр `factor=<число>` — коэффициент,
по которому установленное значение учитывается при расчете среднего.
Допустимы целые числа от `0` до `99`. По умолчанию — `90`.
Чем больше коэффициент, тем сильнее новые значения влияют на среднее.
Если указать `90`, то будет взято `90%` от нового значения
и лишь `10%` от предыдущего.
Примеры:
```nginx
metric_zone avg_exp:1m average exp factor=60;
# В качесте составной метрики:
#
# metric_complex_zone avg_exp:1m {
# some_metric_name average exp factor=60;
# }
server {
listen 80;
location ~ ^/metric/set/(.+)$ {
metric avg_exp KEY=$1;
}
location /api/ {
api /status/http/metric_zones/avg_exp/metrics/;
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/set/100
$ curl 127.0.0.1/metric/set/200
$ curl 127.0.0.1/metric/set/0
$ curl 127.0.0.1/metric/set/8
$ curl 127.0.0.1/metric/set/30
```
Ожидаемое значение метрики в API:
```json
{
"KEY": 30.16
}
```
### average mean
Вычисляет среднее арифметическое. Принимает необязательные параметры
`window=` и `count=<число>`,
задающие соответственно интервал времени и объем выборки для усреднения.
По умолчанию: `window=off` (учитывается вся выборка) и `count=10`.
#### NOTE
Например, `window=5s` будет учитывать только события последних 5 секунд.
Параметрик `window` не может принимать значение `0`. Параметр
`count=число` управляет размером выборки (закэшированных значений)
для более плавного подсчета среднего.
Примеры:
```nginx
metric_zone avg_mean:1m average mean window=5s count=8;
# В качесте составной метрики:
#
# metric_complex_zone avg_mean:1m {
# some_metric_name average mean window=5s count=8;
# }
server {
listen 80;
location ~ ^/metric/set/(.+)$ {
metric avg_mean KEY=$1;
}
location /api/ {
api /status/http/metric_zones/avg_mean/metrics/;
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/set/0.1
$ curl 127.0.0.1/metric/set/0.1
$ curl 127.0.0.1/metric/set/0.4
$ curl 127.0.0.1/metric/set/10
$ curl 127.0.0.1/metric/set/1
$ curl 127.0.0.1/metric/set/1
```
Ожидаемое значение метрики в API:
```json
{
"KEY": 2.1
}
```
Если подождать 5 секунд, с момента последнего обновления метрики, то
ожидаемое значение метрики в API:
```json
{
"KEY": 0
}
```
### histogram
Создает набор "бакетов", увеличивая соответствующий счетчик,
если новое значение не превосходит порога бакета.
Формат параметров — список числовых порогов.
Полезен для анализа распределения, например времени ответа.
В качестве обязательных параметров передаются числа — предельные значения
бакетов, перечисленные в порядке возрастания.
#### NOTE
Значение бакета `inf` или `+Inf` можно использовать
для захвата всех значений, превышающих максимальный бакет.
Примеры:
```nginx
metric_zone hist:1m histogram 0.1 0.2 0.5 1 2 inf;
# В качесте составной метрики:
#
# metric_complex_zone hist:1m {
# some_metric_name histogram 0.1 0.2 0.5 1 2 inf;
# }
server {
listen 80;
location ~ ^/metric/set/(.+)$ {
metric histogram KEY=$1;
}
location /api/ {
api /status/http/metric_zones/hist/metrics/;
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/set/0.25
```
Ожидаемое значение метрики в API:
```json
{
"KEY": {
"0.1": 0,
"0.2": 0,
"0.5": 1,
"1": 1,
"2": 1,
"inf": 1
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/set/2
```
Ожидаемое значение метрики в API:
```json
{
"KEY": {
"0.1": 0,
"0.2": 0,
"0.5": 1,
"1": 1,
"2": 2,
"inf": 2
}
}
```
Обновление метрики:
```console
$ curl 127.0.0.1/metric/set/1000
```
Ожидаемое значение метрики в API:
```json
{
"KEY": {
"0.1": 0,
"0.2": 0,
"0.5": 1,
"1": 1,
"2": 2,
"inf": 3
}
}
```
## Встроенные переменные
Для каждой метрики создаются переменные:
- `$metric_`
- `$metric__key`
- `$metric__value`
Для составной метрики добавляется переменная:
- `$metric__value_`
### `$metric_`
Аналогично директиве [metric](#adc-metric), можно использовать сеттер переменной
`$metric_` для подсчета метрики. Подсчет метрики будет происходить в фазе
[Rewrite](https://angie.software/angie/docs/configuration/modules/http/http_rewrite/),
что позволяет производить обработку метрики, например, из модуля
[njs](https://angie.software/angie/docs/configuration/modules/http/http_js/).
В качестве значения для установки переменной должна использоваться конструкция
`ключ=значение`. В качестве ключа и значения можно использовать текст,
переменные и их комбинации. Ключ — произвольная строка, по которой группируются значения.
Значение — число, обрабатываемое выбранным режимом.
Если пропущено, считается `0`.
Если параметр невозможно преобразовать в число, считается `1`.
Пример использования:
```nginx
http {
metric_zone counter:1m count;
# В этот момент добавилась переменная $metric_counter
server {
listen 80;
location /metric/ {
set $metric_counter $http_user_agent; # Вместо $http_user_agent=0
}
location /api/ {
allow 127.0.0.1;
deny all;
api /status/http/metric_zones/counter/;
}
}
}
```
Подсчет метрики с помощью модуля
[njs](https://angie.software/angie/docs/configuration/modules/http/http_js/):
```nginx
http {
js_import metrics.js;
resolver 127.0.0.53;
metric_complex_zone requests:1m {
min_time min;
max_time max;
total count;
}
location /metric/ {
js_content metrics.js_request;
js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
}
location /api/ {
allow 127.0.0.1;
deny all;
api /static/http/metric_zones/requests/;
}
}
```
Файл `metrics.js`:
```js
async function js_request(r) {
let start_time = Date.now();
let results = await Promise.all([ngx.fetch('https://google.com/'),
ngx.fetch('https://google.ru/')]);
// Используем сеттер переменной $metric_requests
r.variables.metric_requests = `google={Date.now() - start_time}`;
}
export default {js_request};
```
После нескольких запросов на `location /metric/` значения метрики могут быть
следующими:
```json
{
"discarded": 0,
"metrics": {
"google": {
"min_time": 70,
"max_time": 432,
"total": 6
}
}
}
```
#### NOTE
После установки переменной можно получить ее значение. Оно будет равно
указанной паре `ключ=значение`.
Также изменится значение, хранящееся в переменной `$metric__key`
на указанный ключ.
### `$metric__key` и `$metric__value`
Переменные `$metric__key` и `$metric__value` задают
соответственно ключ и значение. Обновление метрики происходит в момент установки
значения `$metric__value`, если ключ в `$metric__key`
уже задан.
#### NOTE
Для составной метрики значения подметрик в переменной `$metric__value`
объединены при помощи разделяющего символа `", "`.
Пример использования:
```nginx
http {
metric_zone gauge:1m gauge;
# В этот момент добавилась переменная $metric_gauge
# А еще переменные $metric_gauge_key и $metric_gauge_value
metric_complex_zone complex:1m {
hist histogram 1 2 3;
avg average exp;
}
# В этот момент добавилась переменная $metric_complex
# А еще переменные $metric_complex_key и $metric_complex_value
server {
listen 80;
location /gauge/ {
set $metric_gauge_key "foo";
set $metric_gauge_value 1;
# Либо set $metric_gauge foo=1;
return 200 "Updated with '$metric_gauge'\nValue='$metric_gauge_value'\n";
}
location /complex/ {
set $metric_complex_key "foo";
set $metric_complex_value 3;
# Либо set $metric_complex foo=3;
return 200 "Updated with '$metric_complex'\nValue='$metric_complex_value'\n";
}
}
}
```
Для такой конфигурации после запроса к `/gauge/` ожидается слудующий ответ:
```console
$ curl 127.0.0.1/gauge/
Updated with 'foo=1'
Value='1'
```
Для `/complex/`:
```console
$ curl 127.0.0.1/complex/
Updated with 'foo=3'
Value='0 0 1, 3'
```
#### NOTE
Если в качестве значения для переменной `$metric__value` указать
пустую строку, значение будет распознано как `0`. Если строка состоит из
символов, которые невозможно преобразовать в число,
она будет распознана как `1`.
Подсчет метрики произойдет только после того, как заданы значения переменных
`$metric__key` и `$metric__value`.
В таком случае значение, сохраненное в `$metric_`, станет равным
новой паре `ключ=значение`, указанной при помощи `$metric__key`
и `$metric__value`.
Значение, которое хранится в `$metric__key`, является последним
указанным через переменные ключом метрики.
Значение, которое хранится в `$metric__value`, является последним
подсчитанным значением метрики с ключом, установленным в `$metric__key`.
### `$metric__value_`
Для составной метрики значение конкретной подметрики можно получить при помощи
переменной `$metric__value_`, указав имя подметрики в качестве
.
Пример использования:
```nginx
http {
metric_complex_zone foo:1m {
count count;
min min;
avg average exp;
}
# В этот момент добавилась переменная $metric_foo
# А еще переменные $metric_foo_key и $metric_foo_value
# А так же $metric_foo_value_count, $metric_foo_value_min и $metric_foo_value_avg
server {
listen 80;
location /foo/ {
set $metric_foo_key bar;
set $metric_foo_value 9;
# Либо set $metric_foo bar=9;
return 200 "Updated with '$metric_foo'\nValues='$metric_foo_value'\nCount='$metric_foo_value_count'\n";
}
}
}
```
Для такой конфигурации после запроса к `/foo/` ожидается слудующий ответ:
```console
$ curl 127.0.0.1/foo/
Updated with 'bar=9'
Values='1, 9, 9'
Count='1'
```
## Дополнительные примеры
### Мониторинг HTTP-методов
```nginx
metric_zone http_methods:1m count;
server {
listen 80;
location / {
metric http_methods $request_method;
}
location /metrics/ {
allow 127.0.0.1;
deny all;
api /status/http/metric_zones/http_methods/metrics/;
}
}
```
Ответ:
```json
{
"GET": 65,
"POST": 20,
"PUT": 10,
"DELETE": 5
}
```
### Распределение времени ответа upstream
```nginx
metric_zone upstream_time:10m expire=on histogram
0.05 0.1 0.3 0.5 1 2 5 10 inf;
server {
listen 80;
location /backend/ {
proxy_pass http://backend;
metric upstream_time $upstream_addr=$upstream_response_time on=end;
}
location /metrics/ {
allow 127.0.0.1;
deny all;
api /status/http/metric_zones/upstream_time/;
}
}
```
Ответ:
```json
{
"discarded": 0,
"metrics": {
"backend1:8080": {
"0.05": 12,
"0.1": 28,
"0.3": 56,
"0.5": 78,
"1": 92,
"2": 97,
"5": 99,
"10": 100,
"inf": 100
}
}
}
```
### Активные подключения
```nginx
metric_zone active_connections:2m gauge;
server {
listen 80;
server_name site1.com;
location / {
# Увеличиваем при подключении
metric active_connections site1=1 on=request;
# Уменьшаем при завершении
metric active_connections site1=-1 on=end;
}
}
server {
listen 80;
server_name site2.com;
location / {
metric active_connections site2=1 on=request;
metric active_connections site2=-1 on=end;
}
}
server {
listen 8080;
location /connections/ {
allow 127.0.0.1;
deny all;
api /status/http/metric_zones/active_connections/metrics;
}
}
```
Ответ:
```json
{
"site1": 42,
"site2": 17
}
```
## Поддержка Prometheus
Angie имеет [встроенный модуль](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus) для отображения метрик в
[формате Prometheus](https://prometheus.io/docs/instrumenting/exposition_formats/),
поддерживающий произвольные метрики.
В качестве примера интеграции рассмотрим следующую конфигурацию:
```nginx
http {
# Создание метрики "upload"
metric_complex_zone upload:1m discard_key="other" {
stats histogram 64 256 1024 4096 16384 +Inf;
sum gauge;
count count;
avg_size average exp;
}
# Описание шаблона Prometheus для метрики "upload"
prometheus_template upload_metric {
'stats{le="$1"}' $p8s_value
path=~^/http/metric_zones/upload/metrics/angie/stats/(.+)$
type=histogram;
'stats_sum' $p8s_value
path=/http/metric_zones/upload/metrics/angie/sum;
'stats_count' $p8s_value
path=/http/metric_zones/upload/metrics/angie/count;
'avg_size' $p8s_value
path=/http/metric_zones/upload/metrics/angie/avg_size;
}
server {
listen 80;
# Обновление метрики
location ~ ^/upload/(.*)$ {
api /status/http/metric_zones/upload/metrics/angie/;
metric upload angie=$1 on=request;
}
# Таргет для сбора метрик
location /prometheus/upload_metric/ {
prometheus upload_metric;
}
}
}
```
После нескольких запросов на `/upload/...`:
```console
$ curl 127.0.0.1/upload/16384
$ curl 127.0.0.1/upload/64448
$ curl 127.0.0.1/upload/64
$ curl 127.0.0.1/upload/1028
$ curl 127.0.0.1/upload/1028
```
Значения метрики будут следующими:
```json
{
"stats": {
"64": 1,
"256": 1,
"1024": 1,
"4096": 3,
"16384": 4,
"+Inf": 5
},
"sum": 82952,
"count": 5,
"avg_size": 1077.9376
}
```
В [формате Prometheus](https://prometheus.io/docs/instrumenting/exposition_formats/)
метрика доступна на `/prometheus/upload_metric/`:
```text
# Angie Prometheus template "upload_metric"
# TYPE stats histogram
stats{le="64"} 1
stats{le="256"} 1
stats{le="1024"} 1
stats{le="4096"} 3
stats{le="16384"} 4
stats{le="+Inf"} 5
stats_sum 82952
stats_count 5
avg_size 1077.9376
```
# https://angie.software/adc/docs/load_balancer/reference/http/http_mirror.md
# Mirror
Позволяет зеркалировать исходный запрос при помощи создания фоновых зеркалирующих подзапросов. Ответы на зеркалирующие подзапросы игнорируются.
## Пример конфигурации
```nginx
location / {
mirror /mirror;
proxy_pass http://backend;
}
location = /mirror {
internal;
proxy_pass http://test_backend$request_uri;
}
```
## Директивы
### mirror
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `mirror` uri | `off`; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | `mirror off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает URI, на который будет зеркалироваться исходный запрос. На одном уровне конфигурации может быть задано несколько зеркал.
### mirror_request_body
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `mirror_request_body` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `mirror_request_body on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, зеркалировать ли тело запроса клиента. Если включено, то тело запроса клиента будет прочитано перед созданием зеркалирующих подзапросов. В этом случае небуферизованное проксирование тела запроса клиента, задаваемое директивами [proxy_request_buffering](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-request-buffering), [fastcgi_request_buffering](https://angie.software//adc/docs/load_balancer/reference/http/http_fastcgi.md#adc-fastcgi-request-buffering), [scgi_request_buffering](https://angie.software//adc/docs/load_balancer/reference/http/http_scgi.md#adc-scgi-request-buffering) и [uwsgi_request_buffering](https://angie.software//adc/docs/load_balancer/reference/http/http_uwsgi.md#adc-uwsgi-request-buffering), будет отключено.
```nginx
location / {
mirror /mirror;
mirror_request_body off;
proxy_pass http://backend;
}
location = /mirror {
internal;
proxy_pass http://log_backend;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
}
```
# https://angie.software/adc/docs/load_balancer/reference/http/http_mp4.md
# MP4
Обеспечивает серверную поддержку псевдо-стриминга для файлов в формате MP4.
Такие файлы обычно имеют расширения .mp4, .m4v и .m4a.
Псевдо-стриминг работает в паре с совместимым медиаплеером. Плеер посылает
серверу HTTP-запрос с указанием точки времени старта в аргументе start строки
запроса (время задается в секундах), а сервер в ответ посылает поток, у которого
начальная позиция соответствует запрошенному времени, например:
```none
http://example.com/elephants_dream.mp4?start=238.88
```
Это позволяет в любой момент времени выполнить произвольное позиционирование, а
также начать воспроизведение с середины временной шкалы.
В форматах, основанных на H.264, метаданные, необходимые для поддержки
позиционирования, хранятся в так называемом "moov-атоме". Это часть файла,
которая содержит индексную информацию для всего файла.
До начала воспроизведения плееру необходимо прочитать метаданные. Для этого он
отсылает специальный запрос с аргументом `start=0`. Многие кодирующие
программы добавляют метаданные в конец файла. Это неоптимально для
псевдо-стриминга, поскольку плееру потребуется загрузить файл целиком прежде чем
начать воспроизведение. Если метаданные находятся в начале файла, Angie
достаточно начать отправлять в ответ содержимое файла. Если же метаданные
находятся в конце файла, потребуется прочитать весь файл и подготовить новый
поток, в котором метаданные предшествуют медийным данным. Это требует
дополнительного процессорного времени, памяти и дискового ввода/вывода, поэтому
лучше заранее [подготовить](https://github.com/flowplayer/flowplayer/wiki/7.1.1-video-file-correction)
исходный файл для псевдо-стриминга, нежели делать это для каждого запроса.
Модуль также поддерживает аргумент `end` HTTP-запроса, задающий время
окончания воспроизведения потока. Аргумент `end` задается совместно с аргументом
`start` или самостоятельно:
```none
http://example.com/elephants_dream.mp4?start=238.88&end=555.55
```
Для запроса с ненулевыми аргументами `start` или `end` Angie
считывает из файла метаданные, готовит поток с запрошенным диапазоном и
отправляет его клиенту. Это тоже требует дополнительных ресурсов, как указано
выше.
Если аргумент `start` указывает на видеокадр, не являющийся ключевым, то
начало такого видео может воспроизводиться с ошибками. В этом случае к
запрашиваемому видео [могут](https://angie.software//angie/docs/configuration/modules/http/http_mp4.md#mp4-start-key-frame) быть добавлены ближайший
к точке `start` ключевой кадр и все промежуточные кадры между ними. При
воспроизведении эти кадры будут скрыты при помощи edit-листа.
Если запрос, обрабатываемый этим модулем, не содержит аргументов `start` и
`end`, дополнительные ресурсы не тратятся, а файл отсылается
непосредственно как статический ресурс. Некоторые плееры также поддерживают
запросы с указанием диапазона запрашиваемых байт (byte-range requests), для них
этот модуль не требуется.
Схожая поддержка псевдо-стриминга для FLV-файлов обеспечивается модулем [FLV](https://angie.software//angie/docs/configuration/modules/http/http_flv.md#http-flv).
## Пример конфигурации
```nginx
location /video/ {
mp4;
mp4_buffer_size 1m;
mp4_max_buffer_size 5m;
}
```
## Директивы
### mp4
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `mp4`; |
|------------------------------------------------------------------------------------------|----------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Включает в содержащем location обработку этим модулем.
### mp4_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `mp4_buffer_size` размер; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `mp4_buffer_size 512K;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает начальный размер буфера, используемого при обработке MP4-файлов.
### mp4_max_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `mp4_max_buffer_size` размер; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `mp4_max_buffer_size 10M;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
В ходе обработки метаданных может понадобиться буфер большего размера. Его размер не может превышать указанного, иначе Angie вернет серверную ошибку 500 (Internal Server Error) и запишет в лог следующее сообщение:
> "/some/movie/file.mp4" mp4 moov atom is too large:
> 12583268, you may want to increase mp4_max_buffer_size
### mp4_limit_rate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `mp4_limit_rate` `on` | `off` | коэффициент; |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| По умолчанию | `mp4_limit_rate off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает скорость передачи запрошенного MP4-файла клиенту.
Предельное значение вычисляется умножением заданного коэффициента
на средний битрейт файла.
- Специальное значение `off` отключает ограничение скорости.
- Специальное значение `on` соответствует коэффициенту `1.1`.
- Начало действия ограничения регулируется значением
[mp4_limit_rate_after](#adc-mp4-limit-rate-after).
Запросы ограничиваются индивидуально:
если клиент открыл два соединения,
общая скорость удваивается.
В связи с этим обратите внимание на [limit_conn](https://angie.software//adc/docs/load_balancer/reference/http/http_api.md#adc-limit-conn) и сопутствующие директивы.
### mp4_limit_rate_after
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `mp4_limit_rate_after` время; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `mp4_limit_rate_after 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает
(в пересчете на
[время воспроизведения](https://angie.software//angie/docs/configuration/configfile.md#syntax))
объем медиаданных,
после передачи которого
скорость будет ограничена директивой
[mp4_limit_rate](#adc-mp4-limit-rate).
### mp4_start_key_frame
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `mp4_start_key_frame` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `mp4_start_key_frame off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Включает режим, в котором видео всегда начинается с ключевого видеокадра. Если аргумент start не указывает на ключевой кадр, то первоначальные кадры будут скрыты при помощи mp4 edit-листа. Edit-листы поддерживаются большинством плееров и браузеров включая Chrome, Safari, QuickTime и ffmpeg, частично поддерживаются в Firefox.
# https://angie.software/adc/docs/load_balancer/reference/http/http_prometheus.md
# Prometheus
Собирает [статистику](https://angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) Angie ADC,
исходя из определенных в конфигурации шаблонов,
и возвращает сформированные на основании этих шаблонов метрики в
[формате Prometheus](https://prometheus.io/docs/instrumenting/exposition_formats/).
#### WARNING
Чтобы собирать статистику,
включите в нужных контекстах зону разделяемой памяти с помощью:
- директивы `zone` в [http_upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone)
или [stream_upstream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone);
- директивы [status_zone](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-status-zone);
- параметра `status_zone` в директиве [resolver](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-resolver).
## Пример конфигурации
Три метрики для сбора статистики запросов к серверным зонам разделяемой памяти,
объединенные в шаблон `custom` и опубликованные по пути `/p8s`:
```nginx
http {
prometheus_template custom {
'angie_http_server_zones_requests_total{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/requests/total$
type=counter;
'angie_http_server_zones_requests_processing{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/requests/processing$
type=gauge;
'angie_http_server_zones_requests_discarded{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/requests/discarded$
type=counter;
}
# ...
server {
listen 80;
location =/p8s {
prometheus custom;
}
# ...
}
}
```
В состав Angie ADC входит вспомогательный файл `prometheus_all.conf`,
куда включен набор общеупотребимых метрик, сведенных в шаблон `all`:
### Содержимое файла
```nginx
prometheus_template all {
angie_connections_accepted $p8s_value
path=/connections/accepted
type=counter
'help=The total number of accepted client connections.';
angie_connections_dropped $p8s_value
path=/connections/dropped
type=counter
'help=The total number of dropped client connections.';
angie_connections_active $p8s_value
path=/connections/active
type=gauge
'help=The current number of active client connections.';
angie_connections_idle $p8s_value
path=/connections/idle
type=gauge
'help=The current number of idle client connections.';
'angie_slabs_pages_used{zone="$1"}' $p8s_value
path=~^/slabs/([^/]+)/pages/used$
type=gauge
'help=The number of currently used memory pages in a slab zone.';
'angie_slabs_pages_free{zone="$1"}' $p8s_value
path=~^/slabs/([^/]+)/pages/free$
type=gauge
'help=The number of currently free memory pages in a slab zone.';
'angie_slabs_pages_slots_used{zone="$1",size="$2"}' $p8s_value
path=~^/slabs/([^/]+)/slots/([^/]+)/used$
type=gauge
'help=The number of currently used memory slots of a specific size in a slab zone.';
'angie_slabs_pages_slots_free{zone="$1",size="$2"}' $p8s_value
path=~^/slabs/([^/]+)/slots/([^/]+)/free$
type=gauge
'help=The number of currently free memory slots of a specific size in a slab zone.';
'angie_slabs_pages_slots_reqs{zone="$1",size="$2"}' $p8s_value
path=~^/slabs/([^/]+)/slots/([^/]+)/reqs$
type=counter
'help=The total number of attempts to allocate a memory slot of a specific size in a slab zone.';
'angie_slabs_pages_slots_fails{zone="$1",size="$2"}' $p8s_value
path=~^/slabs/([^/]+)/slots/([^/]+)/fails$
type=counter
'help=The number of unsuccessful attempts to allocate a memory slot of a specific size in a slab zone.';
'angie_resolvers_queries{zone="$1",type="$2"}' $p8s_value
path=~^/resolvers/([^/]+)/queries/([^/]+)$
type=counter
'help=The number of queries of a specific type to resolve in a resolver zone.';
'angie_resolvers_sent{zone="$1",type="$2"}' $p8s_value
path=~^/resolvers/([^/]+)/sent/([^/]+)$
type=counter
'help=The number of sent DNS queries of a specific type to resolve in a resolver zone.';
'angie_resolvers_responses{zone="$1",status="$2"}' $p8s_value
path=~^/resolvers/([^/]+)/responses/([^/]+)$
type=counter
'help=The number of resolution results with a specific status in a resolver zone.';
'angie_http_server_zones_ssl_handshaked{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/ssl/handshaked$
type=counter
'help=The total number of successful SSL handshakes in an HTTP server zone.';
'angie_http_server_zones_ssl_reuses{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/ssl/reuses$
type=counter
'help=The total number of session reuses during SSL handshakes in an HTTP server zone.';
'angie_http_server_zones_ssl_timedout{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/ssl/timedout$
type=counter
'help=The total number of timed-out SSL handshakes in an HTTP server zone.';
'angie_http_server_zones_ssl_failed{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/ssl/failed$
type=counter
'help=The total number of failed SSL handshakes in an HTTP server zone.';
'angie_http_server_zones_requests_total{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/requests/total$
type=counter
'help=The total number of client requests received in an HTTP server zone.';
'angie_http_server_zones_requests_processing{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/requests/processing$
type=gauge
'help=The number of client requests currently being processed in an HTTP server zone.';
'angie_http_server_zones_requests_discarded{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/requests/discarded$
type=counter
'help=The total number of client requests completed in an HTTP server zone without sending a response.';
'angie_http_server_zones_responses{zone="$1",code="$2"}' $p8s_value
path=~^/http/server_zones/([^/]+)/responses/([^/]+)$
type=counter
'help=The number of responses with a specific status in an HTTP server zone.';
'angie_http_server_zones_data_received{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/data/received$
type=counter
'help=The total number of bytes received from clients in an HTTP server zone.';
'angie_http_server_zones_data_sent{zone="$1"}' $p8s_value
path=~^/http/server_zones/([^/]+)/data/sent$
type=counter
'help=The total number of bytes sent to clients in an HTTP server zone.';
'angie_http_location_zones_requests_total{zone="$1"}' $p8s_value
path=~^/http/location_zones/([^/]+)/requests/total$
type=counter
'help=The total number of client requests in an HTTP location zone.';
'angie_http_location_zones_requests_discarded{zone="$1"}' $p8s_value
path=~^/http/location_zones/([^/]+)/requests/discarded$
type=counter
'help=The total number of client requests completed in an HTTP location zone without sending a response.';
'angie_http_location_zones_responses{zone="$1",code="$2"}' $p8s_value
path=~^/http/location_zones/([^/]+)/responses/([^/]+)$
type=counter
'help=The number of responses with a specific status in an HTTP location zone.';
'angie_http_location_zones_data_received{zone="$1"}' $p8s_value
path=~^/http/location_zones/([^/]+)/data/received$
type=counter
'help=The total number of bytes received from clients in an HTTP location zone.';
'angie_http_location_zones_data_sent{zone="$1"}' $p8s_value
path=~^/http/location_zones/([^/]+)/data/sent$
type=counter
'help=The total number of bytes sent to clients in an HTTP location zone.';
'angie_http_upstreams_peers_backup{upstream="$1",peer="$2"}' $p8st_all_ups_backup
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/backup$
type=gauge
'help=The HTTP upstream peer backup group level.';
'angie_http_upstreams_peers_state{upstream="$1",peer="$2"}' $p8st_all_ups_state
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/state$
type=gauge
'help=The current state of an upstream peer in "HTTP": 1 - up, 2 - down, 3 - unavailable, 4 - recovering, 5 - unhealthy, 6 - checking, 7 - draining, or 8 - busy.';
'angie_http_upstreams_peers_selected_current{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/selected/current$
type=gauge
'help=The number of requests currently being processed by an upstream peer in "HTTP".';
'angie_http_upstreams_peers_selected_total{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/selected/total$
type=counter
'help=The total number of attempts to use an upstream peer in "HTTP".';
'angie_http_upstreams_peers_responses{upstream="$1",peer="$2",code="$3"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/responses/([^/]+)$
type=counter
'help=The number of responses with a specific status received from an upstream peer in "HTTP".';
'angie_http_upstreams_peers_data_sent{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/data/sent$
type=counter
'help=The total number of bytes sent to an upstream peer in "HTTP".';
'angie_http_upstreams_peers_data_received{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/data/received$
type=counter
'help=The total number of bytes received from an upstream peer in "HTTP".';
'angie_http_upstreams_peers_health_fails{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/fails$
type=counter
'help=The total number of unsuccessful attempts to communicate with an upstream peer in "HTTP".';
'angie_http_upstreams_peers_health_unavailable{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/unavailable$
type=counter
'help=The number of times when an upstream peer in "HTTP" became "unavailable" due to reaching the max_fails limit.';
'angie_http_upstreams_peers_health_downtime{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/downtime$
type=counter
'help=The total time (in milliseconds) that an upstream peer in "HTTP" was "unavailable".';
'angie_http_upstreams_peers_health_header_time{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/header_time$
type=gauge
'help=Average time (in milliseconds) to receive the response headers from an upstream peer in "HTTP".';
'angie_http_upstreams_peers_health_response_time{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/response_time$
type=gauge
'help=Average time (in milliseconds) to receive the complete response from an upstream peer in "HTTP".';
'angie_http_upstreams_peers_health_probes_count{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/probes/count$
type=counter
'help=The total number of probes for this peer.';
'angie_http_upstreams_peers_health_probes_fails{upstream="$1",peer="$2"}' $p8s_value
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/health/probes/fails$
type=counter
'help=The total number of failed probes for this peer.';
'angie_http_upstreams_keepalive{upstream="$1"}' $p8s_value
path=~^/http/upstreams/([^/]+)/keepalive$
type=gauge
'help=The number of currently cached keepalive connections for an HTTP upstream.';
'angie_http_upstreams_backup_switch_active{upstream="$1"}' $p8s_value
path=~^/http/upstreams/([^/]+)/backup_switch/active$
type=gauge
'help=The currently active HTTP upstream servers backup group level.';
'angie_http_upstreams_queue_queued{upstream="$1"}' $p8s_value
path=~^/http/upstreams/([^/]+)/queue/queued$
type=counter
'help=The total number of queued requests for an HTTP upstream.';
'angie_http_upstreams_queue_waiting{upstream="$1"}' $p8s_value
path=~^/http/upstreams/([^/]+)/queue/waiting$
type=gauge
'help=The number of requests currently waiting in an HTTP upstream queue.';
'angie_http_upstreams_queue_dropped{upstream="$1"}' $p8s_value
path=~^/http/upstreams/([^/]+)/queue/dropped$
type=counter
'help=The total number of requests dropped from an HTTP upstream queue because the client had prematurely closed the connection.';
'angie_http_upstreams_queue_timedout{upstream="$1"}' $p8s_value
path=~^/http/upstreams/([^/]+)/queue/timedout$
type=counter
'help=The total number of requests timed out from an HTTP upstream queue.';
'angie_http_upstreams_queue_overflows{upstream="$1"}' $p8s_value
path=~^/http/upstreams/([^/]+)/queue/overflows$
type=counter
'help=The total number of requests rejected by an HTTP upstream queue because the size limit had been reached.';
'angie_http_caches_responses{zone="$1",status="$2"}' $p8s_value
path=~^/http/caches/([^/]+)/([^/]+)/responses$
type=counter
'help=The total number of responses processed in an HTTP cache zone with a specific cache status.';
'angie_http_caches_bytes{zone="$1",status="$2"}' $p8s_value
path=~^/http/caches/([^/]+)/([^/]+)/bytes$
type=counter
'help=The total number of bytes processed in an HTTP cache zone with a specific cache status.';
'angie_http_caches_responses_written{zone="$1",status="$2"}' $p8s_value
path=~^/http/caches/([^/]+)/([^/]+)/responses_written$
type=counter
'help=The total number of responses written to an HTTP cache zone with a specific cache status.';
'angie_http_caches_bytes_written{zone="$1",status="$2"}' $p8s_value
path=~^/http/caches/([^/]+)/([^/]+)/bytes_written$
type=counter
'help=The total number of bytes written to an HTTP cache zone with a specific cache status.';
'angie_http_caches_size{zone="$1"}' $p8s_value
path=~^/http/caches/([^/]+)/size$
type=gauge
'help=The current size (in bytes) of cached responses in an HTTP cache zone.';
'angie_http_caches_shards_size{zone="$1",path="$2"}' $p8s_value
path=~^/http/caches/([^/]+)/shards/([^/]+)/size$
type=gauge
'help=The current size (in bytes) of cached responses in a shard path of an HTTP cache zone.';
'angie_http_limit_conns{zone="$1",status="$2"}' $p8s_value
path=~^/http/limit_conns/([^/]+)/([^/]+)$
type=counter
'help=The number of requests processed by an HTTP limit_conn zone with a specific result.';
'angie_http_limit_reqs{zone="$1",status="$2"}' $p8s_value
path=~^/http/limit_reqs/([^/]+)/([^/]+)$
type=counter
'help=The number of requests processed by an HTTP limit_reqs zone with a specific result.';
'angie_stream_server_zones_ssl_handshaked{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/ssl/handshaked$
type=counter
'help=The total number of successful SSL handshakes in a stream server zone.';
'angie_stream_server_zones_ssl_reuses{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/ssl/reuses$
type=counter
'help=The total number of session reuses during SSL handshakes in a stream server zone.';
'angie_stream_server_zones_ssl_timedout{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/ssl/timedout$
type=counter
'help=The total number of timed-out SSL handshakes in a stream server zone.';
'angie_stream_server_zones_ssl_failed{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/ssl/failed$
type=counter
'help=The total number of failed SSL handshakes in a stream server zone.';
'angie_stream_server_zones_connections_total{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/connections/total$
type=counter
'help=The total number of client connections received in a stream server zone.';
'angie_stream_server_zones_connections_processing{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/connections/processing$
type=gauge
'help=The number of client connections currently being processed in a stream server zone.';
'angie_stream_server_zones_connections_discarded{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/connections/discarded$
type=counter
'help=The total number of client connections completed in a stream server zone without establishing a session.';
'angie_stream_server_zones_connections_passed{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/connections/passed$
type=counter
'help=The total number of client connections in a stream server zone passed for handling to a different listening socket.';
'angie_stream_server_zones_sessions{zone="$1",status="$2"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/sessions/([^/]+)$
type=counter
'help=The number of sessions finished with a specific status in a stream server zone.';
'angie_stream_server_zones_data_received{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/data/received$
type=counter
'help=The total number of bytes received from clients in a stream server zone.';
'angie_stream_server_zones_data_sent{zone="$1"}' $p8s_value
path=~^/stream/server_zones/([^/]+)/data/sent$
type=counter
'help=The total number of bytes sent to clients in a stream server zone.';
'angie_stream_upstreams_peers_backup{upstream="$1",peer="$2"}' $p8st_all_ups_backup
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/backup$
type=gauge
'help=The "stream" upstream peer backup group level.';
'angie_stream_upstreams_peers_state{upstream="$1",peer="$2"}' $p8st_all_ups_state
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/state$
type=gauge
'help=The current state of an upstream peer in "stream": 1 - up, 2 - down, 3 - unavailable, 4 - recovering, 5 - unhealthy, 6 - checking, 7 - draining, or 8 - busy.';
'angie_stream_upstreams_peers_selected_current{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/selected/current$
type=gauge
'help=The number of sessions currently being processed by an upstream peer in "stream".';
'angie_stream_upstreams_peers_selected_total{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/selected/total$
type=counter
'help=The total number of attempts to use an upstream peer in "stream".';
'angie_stream_upstreams_peers_data_sent{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/data/sent$
type=counter
'help=The total number of bytes sent to an upstream peer in "stream".';
'angie_stream_upstreams_peers_data_received{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/data/received$
type=counter
'help=The total number of bytes received from an upstream peer in "stream".';
'angie_stream_upstreams_peers_data_pkt_sent{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/data/pkt_sent$
type=counter
'help=The total number of packets sent to an upstream peer in "stream".';
'angie_stream_upstreams_peers_data_pkt_received{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/data/pkt_received$
type=counter
'help=The total number of packets received from an upstream peer in "stream".';
'angie_stream_upstreams_peers_health_fails{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/fails$
type=counter
'help=The total number of unsuccessful attempts to communicate with an upstream peer in "stream".';
'angie_stream_upstreams_peers_health_unavailable{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/unavailable$
type=counter
'help=The number of times when an upstream peer in "stream" became "unavailable" due to reaching the max_fails limit.';
'angie_stream_upstreams_peers_health_downtime{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/downtime$
type=counter
'help=The total time (in milliseconds) that an upstream peer in "stream" was "unavailable".';
'angie_stream_upstreams_peers_health_connect_time{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/connect_time$
type=gauge
'help=Average time (in milliseconds) to connect to an upstream peer in "stream".';
'angie_stream_upstreams_peers_health_first_byte_time{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/first_byte_time$
type=gauge
'help=Average time (in milliseconds) to receive the first byte from an upstream peer in "stream".';
'angie_stream_upstreams_peers_health_last_byte_time{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/last_byte_time$
type=gauge
'help=Average time (in milliseconds) of the whole communication session with an upstream peer in "stream".';
'angie_stream_upstreams_peers_health_probes_count{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/probes/count$
type=counter
'help=The total number of probes for this peer.';
'angie_stream_upstreams_peers_health_probes_fails{upstream="$1",peer="$2"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/peers/([^/]+)/health/probes/fails$
type=counter
'help=The total number of failed probes for this peer.';
'angie_stream_upstreams_backup_switch_active{upstream="$1"}' $p8s_value
path=~^/stream/upstreams/([^/]+)/backup_switch/active$
type=gauge
'help=The currently active "stream" upstream servers backup group level.';
}
'angie_http_acme_clients_state{client="$1"}' $p8st_acme_cert_state
path=~^/http/acme_clients/([^/]+)/state$
type=gauge
'help=The current state of an ACME client: 1 - ready, 2 - requesting, 3 - disabled, or 4 - failed.';
'angie_http_acme_certs_state{client="$1"}' $p8st_acme_cli_state
path=~^/http/acme_clients/([^/]+)/certificate$
type=gauge
'help=The current state of an ACME client certificate: 1 - valid, 2 - mismatch, 3 - expired, 4 - missing, or 5 - error.';
map $p8s_value $p8st_all_ups_state {
volatile;
"up" 1;
"down" 2;
"unavailable" 3;
"recovering" 4;
"unhealthy" 5;
"checking" 6;
"draining" 7;
"busy" 8;
default 0;
}
map $p8s_value $p8st_acme_cli_state {
volatile;
"ready" 1;
"requesting" 2;
"disabled" 3;
"failed" 4;
}
map $p8s_value $p8st_acme_cert_state {
volatile;
"valid" 1;
"mismatch" 2;
"expired" 3;
"missing" 4;
"error" 5;
}
map $p8s_value $p8st_all_ups_backup {
volatile;
"false" 0;
"true" 1;
default $p8s_value;
}
```
Его использование:
```nginx
http {
include prometheus_all.conf;
# ...
server {
listen 80;
location =/p8s {
prometheus all;
}
# ...
}
}
```
```console
$ curl localhost/p8s
# Angie Prometheus template "all"
...
```
## Директивы
### prometheus
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `prometheus` имя_шаблона; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Указывает для контекста `location` шаблон-обработчик,
заданный директивой [prometheus_template](#adc-prometheus-template).
При запросе этот `location` вычисляет и возвращает метрики шаблона
в формате Prometheus.
```nginx
location =/p8s {
prometheus custom;
}
```
```console
$ curl localhost/p8s
# Angie Prometheus template "custom"
...
```
### prometheus_template
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `prometheus_template` имя_шаблона { ... } |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Определяет именованный шаблон метрик, собираемых и экспортируемых Angie,
для использования с директивой [prometheus](#adc-prometheus).
#### NOTE
В состав Angie также входит готовый шаблон [all](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#prometheus-all),
куда включен набор наиболее общеупотребимых метрик.
Может содержать произвольное число определений метрик,
каждая из которых имеет следующую структуру:
<имя_метрики> <переменная> [`path=`<строка_сопоставления>] [`type=`<тип>] [`help=`<справка>].
| `имя_метрики` | Задает имя метрики,
под которым она будет добавлена в формате Prometheus в ответ на запрос.
Может содержать необязательную часть с метками (` *...*`), например:
```none
http_requests_total{method="$1",code="$2"}
```
В значениях меток можно использовать переменные Angie;
если строка_сопоставления задана регулярным выражением,
то можно также использовать определенные в этом выражении группы захвата.
Такие переменные и группы вычисляются при получении значения метрики,
которое задает переменная. |
|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `переменная` | Задает имя переменной, которая будет вычислена и добавлена
как значение метрики в ответ на запрос.
Если переменной нет или результат вычисления пуст (`""`),
метрика не добавляется. |
Метрика вычисляется со значением, которое задает переменная;
при успехе вычисления метрика добавляется в ответ, например:
```nginx
'angie_time{version="$angie_version"}' $msec;
```
```console
$ curl localhost/p8s
angie_time{version="|version|"} 1695119820.562
```
| `path=строка_сопоставления` | Сопоставляется со всеми конечными путями метрик в поддереве
[/status](https://angie.software//angie/docs/configuration/modules/http/http_api.md#metrics)
API-интерфейса Angie,
позволяя добавить в ответ сразу несколько экземпляров метрики. |
|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
При сопоставлении пути берутся с начальной косой чертой, но без конечной,
например `/angie/generation`; при этом регистр символов не учитывается.
Есть два способа сопоставления:
| `path=точное_соответствие` | Проверяется посимвольным сравнением. |
|------------------------------|------------------------------------------------------------------------------------------------------------------------|
| `path=~регулярное_выражение` | Проверяется при помощи библиотеки PCRE; может задавать группы захвата
для использования в метках поля имя метрики. |
Если строка_сопоставления соответствует какому-либо пути,
то значение метрики Angie по нему заносится в переменную
[$p8s_value](https://angie.software//angie/docs/configuration/modules/http/http_prometheus.md#v-p8s-value),
которую при заданном `path=` можно использовать в поле переменная.
Если строка_сопоставления заканчивается конечной косой чертой, значением
метрики будет количество элементов соответствующего списка или объекта.
Например:
```nginx
'angie_http_server_zones_count' $p8s_value
path=/http/server_zones/;
```
В случае регулярного выражения совпадающих путей может быть несколько;
метрика добавляется в ответ для *каждого* совпадения.
В сочетании с группами захвата это позволяет получить ряд метрик
с одним именем и разными метками, например:
```nginx
'angie_slabs_slots_free{zone="$1",size="$2"}' $p8s_value
path=~^/slabs/([^/]+)/slots/([^/]+)/free$;
```
Это определение добавляет метрики для всех зон и всех размеров,
которые есть сейчас в конфигурации:
```none
angie_slabs_slots_free{zone="one",size="8"} 502
angie_slabs_slots_free{zone="one",size="16"} 249
angie_slabs_slots_free{zone="one",size="32"} 122
angie_slabs_slots_free{zone="one",size="128"} 22
angie_slabs_slots_free{zone="one",size="512"} 4
angie_slabs_slots_free{zone="two",size="8"} 311
...
```
Если совпадений нет (при любом способе сопоставления),
то метрика не добавляется.
#### NOTE
Параметр `path=` доступен только
при сборке Angie с модулем [API](https://angie.software//angie/docs/configuration/modules/http/http_api.md#http-api).
| `type=тип`, `help=справка` | Задают соответственно тип и справочную строку метрики в
[формате Prometheus](https://prometheus.io/docs/instrumenting/exposition_formats/#comments-help-text-and-type-information),
которые добавляются с ней в ответ без изменений и проверок. |
|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
## Встроенные переменные
В модуле `http_prometheus` есть встроенная переменная,
получающая значение при сопоставлении путей метрик из раздела
[/status](https://angie.software//angie/docs/configuration/modules/http/http_api.md#metrics)
API-интерфейса Angie
с параметром строка_сопоставления метрик, заданных директивой
[prometheus_template](#adc-prometheus-template).
### `$p8s_value`
Если строка_сопоставления метрики, заданной в [prometheus_template](#adc-prometheus-template),
соответствует какому-либо пути,
то значение метрики Angie, находящееся по этому пути,
заносится в переменную `$p8s_value`.
Она предназначена для использования в поле переменная в определениях метрик,
которые вычисляются на основе параметра `path=`.
Значения метрик Angie, заносимые в переменную `$p8s_value`,
не всегда отвечают потребностям формата Prometheus.
Тогда можно воспользоваться директивой [map](https://angie.software//adc/docs/load_balancer/reference/http/http_map.md#adc-map),
например для преобразования строк в числа:
```nginx
map $p8s_value $ups_state_n {
up 0;
unavailable 1;
down 2;
default 3;
}
prometheus_template main {
'angie_http_upstreams_state{upstream="$1",peer="$2"}' $ups_state_n
path=~^/http/upstreams/([^/]+)/peers/([^/]+)/state$;
}
```
Если у метрики Angie логическое значение, то есть `true` или `false`,
переменная получает значение `"1"` или `"0"` соответственно;
если значение метрики — `null`, то переменная будет равна `"(null)"`.
Для дат используется целочисленный формат эпохи UNIX.
# https://angie.software/adc/docs/load_balancer/reference/http/http_proxy.md
# Proxy
Позволяет передавать запросы другому (проксируемому) серверу.
## Пример конфигурации
```nginx
location / {
proxy_pass http://localhost:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_cache cache_zone;
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
}
```
## Директивы
### proxy_bind
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_bind` адрес [`transparent`] | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает локальный IP-адрес с необязательным портом, который будет использоваться в исходящих соединениях с проксируемым сервером. В значении параметра допустимо использование переменных. Специальное значение `off` отменяет действие унаследованной с предыдущего уровня конфигурации директивы proxy_bind, позволяя системе самостоятельно выбирать локальный IP-адрес и порт.
Параметр `transparent` позволяет задать нелокальный IP-aдрес, который будет использоваться в исходящих соединениях с проксируемым сервером, например, реальный IP-адрес клиента:
```nginx
proxy_bind $remote_addr transparent;
```
Для работы параметра обычно требуется запустить рабочие процессы Angie с привилегиями [суперпользователя](https://angie.software//angie/docs/configuration/modules/core.md#user). В Linux это не требуется, так как если указан параметр transparent, то рабочие процессы наследуют capability CAP_NET_RAW из главного процесса.
#### NOTE
Необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с проксируемого сервера.
### proxy_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_buffer_size` размер; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `proxy_buffer_size 4k|8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает размер буфера, в который будет читаться первая часть ответа, получаемого от проксируемого сервера. В этой части ответа обычно находится небольшой заголовок ответа. По умолчанию размер одного буфера равен размеру страницы памяти. В зависимости от платформы это или 4K, или 8K, однако его можно сделать меньше.
### proxy_buffering
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_buffering` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `proxy_buffering on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает буферизацию ответов от проксируемого сервера.
| `on` | Angie принимает ответ проксируемого сервера как можно быстрее, сохраняя
его в буферы, заданные директивами [proxy_buffer_size](#adc-proxy-buffer-size) и
[proxy_buffers](#adc-proxy-buffers). Отправка клиенту при этом выполняется
параллельно: заполненные буферы передаются на отправку (никто их не
удерживает), но суммарно не более значения
[proxy_busy_buffers_size](#adc-proxy-busy-buffers-size). Если буфер заполнен не полностью, то на
отправку он не передается, если только это не последние данные ответа.
Поэтому для моментальной передачи каждых нескольких байт режим
буферизированного чтения не подходит. Если ответ не вмещается целиком в
память, то его часть может быть записана на диск во [временный файл](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-temp-path). Запись во временные файлы контролируется директивами
[proxy_max_temp_file_size](#adc-proxy-max-temp-file-size) и [proxy_temp_file_write_size](#adc-proxy-temp-file-write-size). |
|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | Ответ передается клиенту сразу же по мере его поступления. Angie работает
в цикле "чтение — отправка" и не ждет, пока буфер заполнится целиком:
например, прочитанные 10 байт из буфера 4К будут сразу отправлены
клиенту. При этом, если весь ответ умещается в буфер, Angie может
прочитать его целиком. Максимальный размер данных, который Angie может
принять от сервера за один раз, задается директивой
[proxy_buffer_size](#adc-proxy-buffer-size). В режиме `off` Angie не кэширует ответы и
не работает [proxy_limit_rate](#adc-proxy-limit-rate). |
Буферизация может быть также включена или выключена путем передачи значения
"yes" или "no" в поле `X-Accel-Buffering` заголовка ответа. Эту
возможность можно запретить с помощью директивы
[proxy_ignore_headers](#adc-proxy-ignore-headers).
### proxy_buffers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_buffers` число размер; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `proxy_buffers 8 4k | 8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число и размер буферов для одного соединения, в которые будет читаться ответ, получаемый от проксируемого сервера.
По умолчанию размер одного буфера равен размеру страницы. В зависимости от платформы это или 4K, или 8K.
### proxy_busy_buffers_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_busy_buffers_size` размер; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `proxy_busy_buffers_size 8k | 16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
При включенной [буферизации](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-buffering) ответов проксируемого сервера, ограничивает суммарный размер буферов, которые могут быть заняты для отправки ответа клиенту, пока ответ еще не прочитан целиком. Оставшиеся буферы тем временем могут использоваться для чтения ответа и, при необходимости, буферизации части ответа во временный файл.
По умолчанию размер ограничен величиной двух буферов, заданных директивами [proxy_buffer_size](#adc-proxy-buffer-size) и [proxy_buffers](#adc-proxy-buffers).
### proxy_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache` зона | `off` [`path=`путь]; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | `proxy_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает зону разделяемой памяти для кэширования.
Одну и ту же зону можно использовать в нескольких местах конфигурации.
В значении параметра допускаются переменные.
| `off` | запрещает кэширование, унаследованное с предыдущего уровня конфигурации. |
|---------|----------------------------------------------------------------------------|
В Angie PRO можно указать несколько директив [proxy_cache_path](#adc-proxy-cache-path),
использующих одно и то же значение `keys_zone`, чтобы включить шардинг
кэша. При этом следует задать параметр `path` директивы
[proxy_cache](#adc-proxy-cache), использующей это значение `keys_zone`:
| `path=`путь | Значение вычисляется в момент *кэширования* ответа от бэкенда
и предполагает использование переменных, в том числе содержащих
информацию из ответа.
Если ответ берется из кэша, то путь не вычисляется заново;
таким образом, кэшированный ответ сохраняет изначальный путь,
пока не будет удален из кэша. |
|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
Это позволяет выбирать нужный путь кэша, применяя директивы [map](https://angie.software//adc/docs/load_balancer/reference/http/http_map.md#adc-map) или
скрипты к ответам от бэкенда. Пример для `Content-Type`:
```nginx
proxy_cache_path /cache/one keys_zone=zone:10m;
proxy_cache_path /cache/two keys_zone=zone;
map $upstream_http_content_type $cache {
~^text/ one;
default two;
}
server {
...
location / {
proxy_pass http://backend;
proxy_cache zone path=/cache/$cache;
proxy_cache_valid 200 10m;
}
}
```
Здесь есть два пути кэша и отображение переменной, чтобы их различать.
Если `Content-Type` начинается с `text/`, будет выбран первый путь,
иначе — второй.
#### NOTE
При использовании [proxy_cache](#adc-proxy-cache)
обычно необходимо также задать директиву [proxy_cache_valid](#adc-proxy-cache-valid),
чтобы явно указать время действия кэшированных ответов.
Если она не задана, Angie не использует значения по умолчанию,
а определяет время хранения ответа в кэше
на основе HTTP-заголовков ответа от сервера в следующем порядке приоритета:
1. Заголовок `X-Accel-Expires` (наивысший приоритет).
2. Заголовок `Cache-Control`
с параметрами `max-age` или `s-maxage`.
3. Заголовок `Expires`.
Если ни один заголовок не содержит допустимого значения или их нет вовсе,
ответ не будет кэшироваться, так как определить срок его действия нельзя.
### proxy_cache_background_update
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_background_update` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| По умолчанию | `proxy_cache_background_update off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запустить фоновый подзапрос для обновления просроченного элемента кэша, в то время как клиенту возвращается устаревший кэшированный ответ.
#### WARNING
Использование устаревшего кэшированного ответа в момент его обновления должно быть [разрешено](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-use-stale-updating).
### proxy_cache_bypass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_bypass` ...; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает условия, при которых ответ не будет браться из кэша. Если значение хотя бы одного из строковых параметров непустое и не равно "0", то ответ не берется из кэша:
```nginx
proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
proxy_cache_bypass $http_pragma $http_authorization;
```
Можно использовать совместно с директивой [proxy_no_cache](#adc-proxy-no-cache).
### proxy_cache_convert_head
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_convert_head` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `proxy_cache_convert_head on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает преобразование метода "HEAD" в "GET" для кэширования. Если преобразование выключено, то необходимо, чтобы [ключ кэширования](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-key) включал в себя [$request_method](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-v-request-method).
### proxy_cache_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_key` строка; |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| По умолчанию | `proxy_cache_key $scheme$proxy_host$request_uri;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает ключ для кэширования, например,
```nginx
proxy_cache_key "$host$request_uri $cookie_user";
```
По умолчанию значение директивы близко к строке
```nginx
proxy_cache_key $scheme$proxy_host$uri$is_args$args;
```
### proxy_cache_lock
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_lock` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `proxy_cache_lock off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если включено, одновременно только одному запросу будет позволено заполнить новый элемент кэша, идентифицируемый согласно директиве [proxy_cache_key](#adc-proxy-cache-key), передав запрос на проксируемый сервер. Остальные запросы этого же элемента будут либо ожидать появления ответа в кэше, либо освобождения блокировки этого элемента, в течение времени, заданного директивой [proxy_cache_lock_timeout](#adc-proxy-cache-lock-timeout).
### proxy_cache_lock_age
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_lock_age` время; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `proxy_cache_lock_age 5s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если последний запрос, переданный на проксируемый сервер для заполнения нового элемента кэша, не завершился за указанное время, на проксируемый сервер может быть передан еще один запрос.
### proxy_cache_lock_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_lock_timeout` время; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `proxy_cache_lock_timeout 5s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут для [proxy_cache_lock](#adc-proxy-cache-lock). По истечении указанного времени запрос будет передан на проксируемый сервер, однако ответ не будет кэширован.
### proxy_cache_max_range_offset
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_max_range_offset` число; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает смещение в байтах для запросов с указанием диапазона запрашиваемых байт (byte-range requests). Если диапазон находится за указанным смещением, range-запрос будет передан на проксируемый сервер и ответ не будет кэширован.
### proxy_cache_methods
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_methods` `GET` | `HEAD` | `POST` ...; |
|------------------------------------------------------------------------------------------|------------------------------------------------------|
| По умолчанию | `proxy_cache_methods GET HEAD;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если метод запроса клиента указан в этой директиве, то ответ будет кэширован. Методы "GET" и "HEAD" всегда добавляются в список, но тем не менее рекомендуется перечислять их явно. См. также директиву [proxy_no_cache](#adc-proxy-no-cache).
### proxy_cache_min_uses
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_min_uses` число; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `proxy_cache_min_uses 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число запросов, после которого ответ будет кэширован.
#### WARNING
Метаданные кэша хранятся в разделяемой памяти. Ручное удаление файлов кэша не
сбрасывает счетчики и может привести к непредсказуемому поведению. Для
полного сброса остановите сервер, удалите директорию кэша и запустите снова.
#### NOTE
Сторонние модули очистки кэша (например, [Cache Purge](https://angie.software//angie/docs/installation/external-modules/cache-purge.md#external-cache-purge)) удаляют только
файлы, но не сбрасывают счетчик proxy_cache_min_uses. Директива
предназначена для защиты кэша от загрязнения редкими запросами, и сброс
счетчика при очистке может негативно повлиять на производительность.
### proxy_cache_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_path` путь [`levels=`уровни] [`use_temp_path=``on` | `off`] `keys_zone=`имя:размер[:`file=`файл] [`inactive=`время] [`max_size=`размер] [`min_free=`размер] [`manager_files=`число] [`manager_sleep=`время] [`manager_threshold=`время] [`loader_files=`число] [`loader_sleep=`время] [`loader_threshold=`время]; |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает путь и другие параметры кэша. Данные кэша хранятся в файлах. Именем файла в кэше является результат функции MD5 от [ключа кэширования](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-key).
| `levels` | задает уровни иерархии кэша: можно задать от 1 до 3 уровней, на каждом уровне допускаются значения 1 или 2. |
|------------|---------------------------------------------------------------------------------------------------------------|
Например, при использовании
```nginx
proxy_cache_path /data/angie/cache levels=1:2 keys_zone=one:10m;
```
имена файлов в кэше будут такого вида:
```nginx
/data/angie/cache/c/29/b7f54b2df7773722d382f4809d65029c
```
Кэшируемый ответ сначала записывается во временный файл, а потом этот файл переименовывается. Временные файлы и кэш могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешевой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если кэш будет находиться на той же файловой системе, что и каталог с временными файлами.
| `use_temp_path=on` | `off` | определяет каталог, который будет использоваться для временных файлов |
|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `on` | Если параметр не задан или установлен в значение `on`, будет использоваться каталог, задаваемый директивой [proxy_temp_path](#adc-proxy-temp-path) для данного location |
| `off` | временные файлы будут располагаться непосредственно в каталоге кэша |
| `keys_zone` | Задает имя и размер зоны разделяемой памяти для хранения всех активных ключей и информации о данных. Метаданные кэша хранятся в разделяемой памяти.
Зоны размером в 1 мегабайт достаточно для хранения около 8000 ключей.
Когда с `keys_zone` задан необязательный файл,
Angie сбрасывает содержимое этой зоны на диск
при завершении работы основного процесса
и пытается восстановить ее по тому же адресу памяти
при следующем [запуске](https://angie.software//angie/docs/configuration/runtime.md#runtime)
или после [обновления бинарных файлов](https://angie.software//angie/docs/configuration/runtime.md#service-upgrade),
чтобы обеспечить более надежную сохраняемость данных
и сократить время загрузки кэша.
Если восстановление области невозможно из-за изменения ее размера,
несовместимости версий бинарных файлов или по другим причинам,
Angie запишет в журнал предупреждение (`failed to restore zone at address`)
и не будет использовать механизм восстановления зоны.
Вместо этого несовместимый файл будет переименован в `.old`;
вы можете либо удалить его,
либо восстановить его имя и вернуть Angie к конфигурации и версии,
в которых этот файл был изначально создан.
#### WARNING
Убедитесь, что путь к файлу указан правильно
и имеет необходимые права доступа для использования Angie,
а также защищен от несанкционированного доступа;
относительные пути основаны на [префиксе](https://angie.software//angie/docs/installation/sourcebuild.md#paths). |
| `inactive` | Если к данным кэша не обращаются в течение времени, заданного этим параметром, то данные удаляются, независимо от их свежести.
По умолчанию `inactive` равен 10 минутам. |
#### NOTE
В Angie PRO можно задавать несколько директив proxy_cache_path с одним и
тем же значением `keys_zone`. Размер зоны разделяемой памяти можно
указывать только в первой из них. Выбор между директивами будет
производиться на основе параметра `path` соответствующей директивы
[proxy_cache](#adc-proxy-cache).
Специальный процесс **менеджера кэша** следит за максимальным размером кэша, а также за минимальным объемом свободного места на файловой системе с кэшем, и удаляет наименее востребованные данные при превышении максимального размера кэша или недостаточном объеме свободного места. Удаление данных происходит итерациями.
| `max_size` | максимальное пороговое значение размера кэша |
|---------------------|---------------------------------------------------------------------------------------------------------|
| `min_free` | минимальное пороговое значение объема свободного места на файловой системе с кэшем |
| `manager_files` | максимальное количество удаляемых элементов кэша за одну итерацию
По умолчанию: `100`. |
| `manager_threshold` | ограничивает время работы одной итерации
По умолчанию: `200` миллисекунд. |
| `manager_sleep` | время, в течение которого выдерживается пауза между итерациями
По умолчанию: `50` миллисекунд. |
Через минуту после запуска Angie активируется специальный процесс **загрузчика кэша**.
Он сканирует файловую систему в поисках ранее закэшированных данных
и загружает эту информацию в область кэша.
Этот процесс выполняется итеративно;
каждая итерация обрабатывает ограниченное количество элементов, заданное параметром `loader_files`,
следит за тем, чтобы не превышать `loader_threshold`,
затем делает короткую паузу, заданную `loader_sleep`,
перед переходом к следующей партии.
Итерации продолжаются
до тех пор, пока загрузчик не обработает все существующие записи кэша на диске:
| `loader_files` | максимальное количество элементов кэша к загрузке в одну итерацию
По умолчанию: `100` |
|--------------------|--------------------------------------------------------------------------------------------------------|
| `loader_threshold` | ограничивает время работы одной итерации
По умолчанию: `200` миллисекунд |
| `loader_sleep` | время, в течение которого выдерживается пауза между итерациями
По умолчанию: `50` миллисекунд |
#### NOTE
Указание файла для параметра `keys_zone`
не влияет на работу загрузчика кэша.
### proxy_cache_revalidate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_revalidate` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `proxy_cache_revalidate off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает ревалидацию просроченных элементов кэша при помощи условных запросов с полями заголовка `If-Modified-Since` и `If-None-Match` .
### proxy_cache_use_stale
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_use_stale` `error` | `timeout` | `invalid_header` | `updating` | `http_500` | `http_502` | `http_503` | `http_504` | `http_403` | `http_404` | `http_429` | `off` ...; |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `proxy_cache_use_stale off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, в каких случаях можно использовать устаревший кэшированный ответ. Параметры директивы совпадают с параметрами директивы [proxy_next_upstream](#adc-proxy-next-upstream).
| `error` | Позволяет использовать устаревший кэшированный ответ при невозможности выбора проксированного сервера для обработки запроса. |
|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `updating` | Дополнительный параметр, разрешает использовать устаревший кэшированный ответ, если на данный момент он уже обновляется. Это позволяет минимизировать число обращений к проксированным серверам при обновлении кэшированных данных. |
Использование устаревшего кэшированного ответа может также быть разрешено непосредственно в заголовке ответа на определенное количество секунд после того, как ответ устарел:
* Расширение [stale-while-revalidate](https://datatracker.ietf.org/doc/html/rfc5861#section-3) поля заголовка `Cache-Control` разрешает использовать устаревший кэшированный ответ, если на данный момент он уже обновляется.
* Расширение [stale-if-error](https://datatracker.ietf.org/doc/html/rfc5861#section-4) поля заголовка `Cache-Control` разрешает использовать устаревший кэшированный ответ в случае ошибки.
#### NOTE
Такой способ менее приоритетен, чем задание параметров директивы.
Чтобы минимизировать число обращений к проксированным серверам при заполнении нового элемента кэша, можно воспользоваться директивой [proxy_cache_lock](#adc-proxy-cache-lock).
### proxy_cache_valid
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_valid` [код ...] время; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает время кэширования для разных кодов ответа. Например, директивы
```nginx
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
```
задают время кэширования 10 минут для ответов с кодами 200 и 302 и 1 минуту для ответов с кодом 404.
Если указано только время кэширования,
```nginx
proxy_cache_valid 5m;
```
то кэшируются только ответы 200, 301 и 302.
Кроме того, можно кэшировать любые ответы с помощью параметра `any`:
```nginx
proxy_cache_valid 200 302 10m;
proxy_cache_valid 301 1h;
proxy_cache_valid any 1m;
```
#### NOTE
Параметры кэширования могут также быть заданы непосредственно в заголовке ответа. Такой способ приоритетнее, чем задание времени кэширования с помощью директивы.
* Поле заголовка `X-Accel-Expires` задает время кэширования ответа в секундах. Значение 0 запрещает кэшировать ответ. Если значение начинается с префикса @, оно задает абсолютное время в секундах с начала эпохи, до которого ответ может быть кэширован.
* Если в заголовке нет поля `X-Accel-Expires`, параметры кэширования определяются по полям заголовка `Expires` или `Cache-Control`.
* Ответ, в заголовке которого есть поле `Set-Cookie`, не будет кэшироваться.
* Ответ, в заголовке которого есть поле `Vary` со специальным значением "\*", не будет кэшироваться. Ответ, в заголовке которого есть поле `Vary` с другим значением, будет кэширован с учетом соответствующих полей заголовка запроса.
Обработка одного или более из этих полей заголовка может быть отключена при помощи директивы [proxy_ignore_headers](#adc-proxy-ignore-headers).
### proxy_connect_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_connect_timeout` время; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `proxy_connect_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут для установления соединения с проксированным сервером. Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.
### proxy_connection_drop
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_connection_drop` время | `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| По умолчанию | `proxy_connection_drop off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Настраивает завершение всех соединений с проксируемым сервером,
если он был удален из группы или помечен как постоянно недоступный
в результате процесса [reresolve](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve)
или [команды API](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods) `DELETE`.
Соединение завершается, когда обрабатывается следующее событие чтения или записи
для клиента или проксируемого сервера.
Установка времени включает [таймаут](https://angie.software//angie/docs/configuration/configfile.md#syntax) до завершения соединения;
при выборе значения `on` соединения завершаются немедленно.
### proxy_cookie_domain
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cookie_domain` `off`;
`proxy_cookie_domain` домен замена; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| По умолчанию | `proxy_cookie_domain off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает текст, который нужно изменить в атрибуте domain полей `Set-Cookie` заголовка ответа проксируемого сервера. Предположим, проксируемый сервер вернул поле заголовка `Set-Cookie` с атрибутом "domain=localhost". Директива
```nginx
proxy_cookie_domain localhost example.org;
```
перепишет данный атрибут в виде "domain=example.org".
Точка в начале строк домен и замена, а равно как и в атрибуте domain игнорируется. Регистр значения не имеет.
В строках домен и замена можно использовать переменные:
```nginx
proxy_cookie_domain www.$host $host;
```
Директиву также можно задать при помощи регулярных выражений. При этом домен должен начинаться с символа "~". Регулярное выражение может содержать именованные и позиционные группы захвата, а замена ссылаться на них:
```nginx
proxy_cookie_domain ~\.(?P[-0-9a-z]+\.[a-z]+)$ $sl_domain;
```
На одном уровне может быть указано несколько директив proxy_cookie_domain:
```nginx
proxy_cookie_domain localhost example.org;
proxy_cookie_domain ~\.([a-z]+\.[a-z]+)$ $1;
```
Если к cookie могут быть применены несколько директив, будет выбрана первая из них.
Параметр `off` отменяет действие унаследованных с предыдущего уровня конфигурации директив proxy_cookie_domain.
### proxy_cookie_flags
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cookie_flags` `off` | cookie [флаг ...]; |
|------------------------------------------------------------------------------------------|---------------------------------------------------|
| По умолчанию | `proxy_cookie_flags off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает один или несколько флагов для cookie. В качестве cookie можно использовать текст, переменные и их комбинации. В качестве флага можно использовать текст, переменные и их комбинации.
Параметры secure, httponly, samesite=strict, samesite=lax, samesite=none добавляют соответствующие флаги.
Параметры nosecure, nohttponly, nosamesite удаляют соответствующие флаги.
Cookie также можно задать при помощи регулярных выражений. При этом cookie должен начинаться с символа "~".
На одном уровне конфигурации может быть указано несколько директив proxy_cookie_flags:
```nginx
proxy_cookie_flags one httponly;
proxy_cookie_flags ~ nosecure samesite=strict;
```
Если к cookie могут быть применены несколько директив, будет выбрана первая из них. В данном примере флаг httponly добавляется к cookie one, для остальных cookie добавляется флаг samesite=strict и удаляется флаг secure.
Параметр `off` отменяет действие всех директив proxy_cookie_flags на данном уровне.
### proxy_cookie_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cookie_path` `off`;
`proxy_cookie_path` путь замена; |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| По умолчанию | `proxy_cookie_path off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает текст, который нужно изменить в атрибуте path полей `Set-Cookie` заголовка ответа проксируемого сервера. Предположим, проксируемый сервер вернул поле заголовка `Set-Cookie` с атрибутом "path=/two/some/uri/". Директива
```nginx
proxy_cookie_path /two/ /;
```
перепишет данный атрибут в виде "path=/some/uri/".
В строках путь и замена можно использовать переменные:
```nginx
proxy_cookie_path $uri /some$uri;
```
Директиву также можно задать при помощи регулярных выражений. При этом путь должен начинаться либо с символа "~", если при сравнении следует учитывать регистр символов, либо с символов "~\*", если регистр символов учитывать не нужно. Регулярное выражение может содержать именованные и позиционные группы захвата, а замена ссылаться на них:
```nginx
proxy_cookie_path ~*^/user/([^/]+) /u/$1;
```
На одном уровне может быть указано несколько директив proxy_cookie_path:
```nginx
proxy_cookie_path /one/ /;
proxy_cookie_path / /two/;
```
Если к cookie могут быть применены несколько директив, будет выбрана первая из них.
Параметр `off` отменяет действие унаследованных с предыдущего уровня конфигурации директив proxy_cookie_path.
### proxy_force_ranges
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_force_ranges` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `proxy_force_ranges off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Включает поддержку диапазонов запрашиваемых байт (byte-range) для кэшированных и некэшированных ответов проксируемого сервера вне зависимости от наличия поля `Accept-Ranges` в заголовках этих ответов.
### proxy_headers_hash_bucket_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_headers_hash_bucket_size` размер; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `proxy_headers_hash_bucket_size 64;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает размер корзины для хэш-таблиц, используемых директивами [proxy_hide_header](#adc-proxy-hide-header) и [proxy_set_header](#adc-proxy-set-header). Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
### proxy_headers_hash_max_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_headers_hash_max_size` размер; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `proxy_headers_hash_max_size 512;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает максимальный размер хэш-таблиц, используемых директивами [proxy_hide_header](#adc-proxy-hide-header) и [proxy_set_header](#adc-proxy-set-header). Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
### proxy_hide_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_hide_header` поле; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
По умолчанию Angie не передает клиенту поля заголовка `Date`, `Server`, `X-Pad` и `X-Accel-...` из ответа проксированного сервера. Директива proxy_hide_header задает дополнительные поля, которые не будут передаваться. Если же передачу полей нужно разрешить, можно воспользоваться директивой [proxy_pass_header](#adc-proxy-pass-header).
### proxy_http_version
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_http_version` `1.0` | `1.1` | `3`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------|
| По умолчанию | `proxy_http_version 1.0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location, limit_except |
Задает версию протокола HTTP для проксирования.
По умолчанию используется версия 1.0.
Для работы
[постоянных соединений](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive)
рекомендуется версия 1.1 или выше.
### proxy_http3_hq
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_http3_hq` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `proxy_http3_hq off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Отключает или включает особый режим cогласования `hq-interop`,
используемый в
[функциональных тестах](https://github.com/marten-seemann/quic-interop-runner)
[QUIC](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version),
на которые полагается Angie.
#### WARNING
Включайте этот режим только для запуска специализированных тестов,
которым в явной форме необходим данный режим.
### proxy_http3_max_concurrent_streams
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_http3_max_concurrent_streams` число; |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| По умолчанию | `proxy_http3_max_concurrent_streams 128;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Инициализирует настройки HTTP/3 и QUIC,
а также задает максимальное число параллельных HTTP/3-потоков в
[соединении](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version).
Требует включения [постоянных соединений](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive).
### proxy_http3_max_table_capacity
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_http3_max_table_capacity` число; |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| Значение по умолчанию | `proxy_http3_max_table_capacity 4096;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет емкость [динамической таблицы](https://www.ietf.org/archive/id/draft-ietf-quic-qpack-20.html#name-dynamic-table)
для прокси-соединений.
#### NOTE
Похожая директива [http3_max_table_capacity](https://angie.software//adc/docs/load_balancer/reference/http/http_v3.md#adc-http3-max-table-capacity)
задает это значение для серверных соединений.
Чтобы избежать ошибок, использование динамической таблицы
отключается при включенном кэшировании в режиме проксирования.
### proxy_http3_stream_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_http3_stream_buffer_size` размер; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `proxy_http3_stream_buffer_size 64k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает [размер](https://angie.software//angie/docs/configuration/configfile.md#syntax) буфера, используемого для чтения и записи
[QUIC-потоков](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version).
### proxy_ignore_client_abort
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ignore_client_abort` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | `proxy_ignore_client_abort off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, закрывать ли соединение с проксируемым сервером в случае, если клиент закрыл соединение, не дождавшись ответа.
### proxy_ignore_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ignore_headers` поле ...; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Запрещает обработку некоторых полей заголовка из ответа проксированного сервера. В директиве можно указать поля `X-Accel-Redirect`, `X-Accel-Expires`, `X-Accel-Limit-Rate`, `X-Accel-Buffering`, `X-Accel-Charset`, `Expires`, `Cache-Control`, `Set-Cookie` и `Vary`.
Если не запрещено, обработка этих полей заголовка заключается в следующем:
* `X-Accel-Expires`, `Expires`, `Cache-Control`, `Set-Cookie` и `Vary` задают [параметры кэширования](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-valid) ответа;
* `X-Accel-Redirect` производит [внутреннее перенаправление](https://angie.software//angie/docs/configuration/modules/http/index.md#internal) на указанный URI;
* `X-Accel-Limit-Rate` задает [ограничение скорости](https://angie.software//angie/docs/configuration/modules/http/index.md#limit-rate) передачи ответа клиенту;
* `X-Accel-Buffering` включает или выключает [буферизацию](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-buffering) ответа;
* `X-Accel-Charset` задает желаемую [кодировку](https://angie.software//angie/docs/configuration/modules/http/http_charset.md#id3) ответа.
### proxy_intercept_errors
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_intercept_errors` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `proxy_intercept_errors off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, передавать ли клиенту проксированные ответы с кодом больше либо равным 300, или же перехватывать их и перенаправлять на обработку Angie с помощью директивы [error_page](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-error-page).
### proxy_limit_rate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_limit_rate` скорость; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `proxy_limit_rate 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает скорость чтения ответа от проксируемого сервера.
Скорость задается в байтах в секунду; можно использовать переменные.
| `0` | отключает ограничение скорости |
|-------|----------------------------------|
#### NOTE
Ограничение устанавливается на запрос, поэтому, если Angie одновременно откроет два соединения к проксируемому серверу, суммарная скорость будет вдвое выше заданного ограничения. Ограничение работает только в случае, если включена [буферизация](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-buffering) ответов проксируемого сервера.
### proxy_max_temp_file_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_max_temp_file_size` размер; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `proxy_max_temp_file_size 1024m;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если включена [буферизация](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-buffering) ответов проксируемого сервера, и ответ не вмещается целиком в буферы, заданные директивами [proxy_buffer_size](#adc-proxy-buffer-size) и [proxy_buffers](#adc-proxy-buffers), часть ответа может быть записана во временный файл. Эта директива задает максимальный размер временного файла. Размер данных, сбрасываемых во временный файл за один раз, задается директивой [proxy_temp_file_write_size](#adc-proxy-temp-file-write-size).
| `0` | отключает возможность буферизации ответов во временные файлы |
|-------|----------------------------------------------------------------|
#### NOTE
Данное ограничение не распространяется на ответы, которые будут [кэшированы](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache) или сохранены [на диске](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-store).
### proxy_method
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_method` метод; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает HTTP-метод, который будет использоваться в передаваемых на проксируемый сервер запросах вместо метода из клиентского запроса. В значении параметра допустимо использование переменных.
### proxy_next_upstream
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_next_upstream` `error` | `timeout` | `invalid_header` | `http_500` | `http_502` | `http_503` | `http_504` | `http_403` | `http_404` | `http_429` | `non_idempotent` | `off` ...; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `proxy_next_upstream error timeout;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, в каких случаях запрос будет передан следующему в группе [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) серверу:
| `error` | произошла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `timeout` | произошел таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
| `invalid_header` | сервер вернул пустой или неверный ответ; |
| `http_500` | сервер вернул ответ с кодом 500; |
| `http_502` | сервер вернул ответ с кодом 502; |
| `http_503` | сервер вернул ответ с кодом 503; |
| `http_504` | сервер вернул ответ с кодом 504; |
| `http_403` | сервер вернул ответ с кодом 403; |
| `http_404` | сервер вернул ответ с кодом 404; |
| `http_429` | сервер вернул ответ с кодом 429; |
| `non_idempotent` | обычно запросы с [неидемпотентным](https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2) методом (POST, LOCK, PATCH) не передаются на другой сервер, если запрос серверу группы уже был отправлен; включение параметра явно разрешает повторять подобные запросы; |
| `off` | запрещает передачу запроса следующему серверу. |
Если все upstream‑серверы недоступны или возвращают ответ со статусом,
считающимся ошибкой для `proxy_next_upstream`, Angie возвращает
собственную стандартную страницу ошибки вместо тела ответа от последнего
upstream‑сервера.
#### NOTE
Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту еще ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа клиенту, то действие директивы на такой запрос не распространяется.
Директива также определяет, что считается [неудачной попыткой](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) работы с сервером.
| `error`
`timeout`
`invalid_header` | всегда считаются неудачными попытками, даже если они не указаны в директиве |
|--------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
| `http_500`
`http_502`
`http_503`
`http_504`
`http_429` | считаются неудачными попытками, только если они указаны в директиве |
| `http_403`
`http_404` | никогда не считаются неудачными попытками |
Передача запроса следующему серверу может быть ограничена по [количеству попыток](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream-tries) и по [времени](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream-timeout).
### proxy_next_upstream_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_next_upstream_timeout` время; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `proxy_next_upstream_timeout 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает время, в течение которого возможна передача запроса [следующему](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### proxy_next_upstream_tries
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_next_upstream_tries` число; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `proxy_next_upstream_tries 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает число допустимых попыток для передачи запроса [следующему](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### proxy_no_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_no_cache` строка ...; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает условия, при которых ответ не будет сохраняться в кэш. Если значение хотя бы одного из строковых параметров непустое и не равно "0", то ответ не будет сохранен:
```nginx
proxy_no_cache $cookie_nocache $arg_nocache$arg_comment;
proxy_no_cache $http_pragma $http_authorization;
```
Можно использовать совместно с директивой [proxy_cache_bypass](#adc-proxy-cache-bypass).
### proxy_pass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_pass` uri; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location, if в location, limit_except |
Задает протокол и адрес проксируемого сервера, а также необязательный URI, на который должен отображаться location. В качестве протокола можно указать `http` или `https`. Адрес может быть указан в виде доменного имени или IP-адреса, и необязательного порта:
```nginx
proxy_pass http://localhost:8000/uri/;
```
или в виде пути UNIX-сокета, который указывается после слова `unix` и заключается в двоеточия:
```nginx
proxy_pass http://unix:/tmp/backend.socket:/uri/;
```
Если доменному имени соответствует несколько адресов, то все они будут использоваться по очереди (round-robin). Кроме того, в качестве адреса можно указать [группу серверов](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).
В значении параметра можно использовать переменные. В этом случае, если адрес указан в виде доменного имени, имя ищется среди описанных групп серверов и если не найдено, то определяется с помощью [resolver](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-resolver)'а.
URI запроса передается на сервер так:
* Если директива `proxy_pass` указана **с URI**, то при передаче запроса серверу часть [нормализованного](https://angie.software//angie/docs/configuration/modules/http/index.md#location) URI запроса, соответствующая location, заменяется на URI, указанный в директиве:
```nginx
location /name/ {
proxy_pass http://127.0.0.1/remote/;
}
```
* Если директива `proxy_pass` указана **без URI**, то при обработке первоначального запроса на сервер передается URI запроса в том же виде, в каком его прислал клиент, а при обработке измененного URI - нормализованный URI запроса целиком:
```nginx
location /some/path/ {
proxy_pass http://127.0.0.1;
}
```
В ряде случаев часть URI запроса, подлежащую замене, выделить невозможно:
* Если `location` задан регулярным выражением, а также в именованных `location`.
В этих случаях `proxy_pass` следует указывать без URI.
* Если внутри проксируемого `location` с помощью директивы [rewrite](https://angie.software//adc/docs/load_balancer/reference/http/http_rewrite.md#adc-rewrite) изменяется URI, и именно с этой конфигурацией будет обрабатываться запрос (break):
```nginx
location /name/ {
rewrite /name/([^/]+) /users?name=$1 break;
proxy_pass http://127.0.0.1;
}
```
В этом случае URI, указанный в директиве, игнорируется, и на сервер передается измененный URI запроса целиком.
* При использовании переменных в proxy_pass:
```nginx
location /name/ {
proxy_pass http://127.0.0.1$request_uri;
}
```
В этом случае если в директиве указан URI, он передается на сервер как есть, заменяя URI первоначального запроса.
Проксирование WebSocket требует особой [настройки](https://angie.software//angie/docs/configuration/processing.md#websocket-proxy).
#### NOTE
Если `proxy_pass` стоит в `location` с косой чертой в конце префикса
(например, `location /name/`),
и при этом в директиве [auto_redirect](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-auto-redirect) указано `default`,
запросы без косой черты в конце будут перенаправляться (`/name -> /name/`).
### proxy_pass_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_pass_header` поле ...; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает передавать от проксируемого сервера клиенту [запрещенные для передачи](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-hide-header) поля заголовка.
### proxy_pass_request_body
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_pass_request_body` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| По умолчанию | `proxy_pass_request_body on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запретить передачу исходного тела запроса на проксируемый сервер.
```nginx
location /x-accel-redirect-here/ {
proxy_method GET;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_pass ...;
}
```
См. также директивы [proxy_set_header](#adc-proxy-set-header) и [proxy_pass_request_headers](#adc-proxy-pass-request-headers).
### proxy_pass_request_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_pass_request_headers` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | `proxy_pass_request_headers on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запретить передачу полей заголовка исходного запроса на проксируемый сервер.
```nginx
location /x-accel-redirect-here/ {
proxy_method GET;
proxy_pass_request_headers off;
proxy_pass_request_body off;
proxy_pass ...;
}
```
См. также директивы [proxy_set_header](#adc-proxy-set-header) и [proxy_pass_request_body](#adc-proxy-pass-request-body).
### proxy_pass_trailers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_pass_trailers` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `proxy_pass_trailers off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает передачу полей трейлеров от проксируемого сервера клиенту.
Секция трейлеров в HTTP/1.1 [включается явно](https://datatracker.ietf.org/doc/html/rfc9110#section-6.5.1).
```nginx
location / {
proxy_http_version 1.1;
proxy_set_header Connection "te";
proxy_set_header TE "trailers";
proxy_pass_trailers on;
proxy_pass ...;
}
```
### proxy_quic_active_connection_id_limit
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_quic_active_connection_id_limit` число; |
|------------------------------------------------------------------------------------------|--------------------------------------------------|
| По умолчанию | `proxy_quic_active_connection_id_limit 2;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает значение транспортного параметра [QUIC](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version)
`active_connection_id_limit`.
Это максимальное число активных
[идентификаторов соединений](https://www.rfc-editor.org/rfc/rfc9000.html#name-connection-id),
поддерживаемых для одного сервера.
### proxy_quic_gso
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_quic_gso` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `proxy_quic_gso off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Отключает или включает отправку данных в оптимизированном пакетном режиме
[QUIC](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version),
использующем программное снижение нагрузки путем сегментации
([generic segmentation offload](https://docs.kernel.org/networking/segmentation-offloads.html#generic-segmentation-offload)).
### proxy_quic_host_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_quic_host_key` файл; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает файл с секретным ключом,
применяемым в
[QUIC](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version)
при шифровании токенов
[Stateless Reset](https://www.rfc-editor.org/rfc/rfc9000.html#name-stateless-reset)
и
[Address Validation](https://www.rfc-editor.org/rfc/rfc9000.html#address-validation).
По умолчанию случайный ключ создается при каждом перезапуске.
Токены, созданные при помощи старых ключей, не принимаются.
### proxy_read_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_read_timeout` время; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `proxy_read_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при чтении ответа проксированного сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени проксируемый сервер ничего не передаст, соединение закрывается.
### proxy_redirect
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_redirect` `default`;
`proxy_redirect` `off`;
`proxy_redirect` перенаправление замена; |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `proxy_redirect default;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает текст, который нужно изменить в полях заголовка "Location" и "Refresh" в ответе проксируемого сервера.
Предположим, проксируемый сервер вернул поле заголовка:
```console
Location: http://localhost:8000/two/some/uri/
```
Директива
```nginx
proxy_redirect http://localhost:8000/two/ http://frontend/one/;
```
перепишет эту строку в виде:
```console
Location: http://frontend/one/some/uri/
```
В заменяемой строке можно не указывать имя сервера:
```nginx
proxy_redirect http://localhost:8000/two/ /;
```
тогда будут подставлены основное имя сервера и порт, если он отличен от 80.
Стандартная замена, задаваемая параметром `default`, использует параметры директив [location](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-location) и [proxy_pass](#adc-proxy-pass). Поэтому две нижеприведенные конфигурации одинаковы:
```nginx
location /one/ {
proxy_pass http://upstream:port/two/;
proxy_redirect default;
```
```nginx
location /one/ {
proxy_pass http://upstream:port/two/;
proxy_redirect http://upstream:port/two/ /one/;
```
#### WARNING
Параметр `default` недопустим, если в [proxy_pass](#adc-proxy-pass) используются переменные.
В строке замена можно использовать переменные:
```nginx
proxy_redirect http://localhost:8000/ http://$host:$server_port/;
```
В строке перенаправление тоже можно использовать переменные:
```nginx
proxy_redirect http://$proxy_host:8000/ /;
```
Директиву также можно задать при помощи регулярных выражений. При этом перенаправление должно начинаться либо с символа "~", если при сравнении следует учитывать регистр символов, либо с символов "~\*", если регистр символов учитывать не нужно. Регулярное выражение может содержать именованные и позиционные группы захвата, а замена ссылаться на них:
```nginx
proxy_redirect ~^(http://[^:]+):\d+(/.+)$ $1$2;
proxy_redirect ~*/user/([^/]+)/(.+)$ http://$1.example.com/$2;
```
На одном уровне может быть указано несколько директив proxy_redirect:
```nginx
proxy_redirect default;
proxy_redirect http://localhost:8000/ /;
proxy_redirect http://www.example.com/ /;
```
Если к полям заголовка в ответе проксируемого сервера могут быть применены несколько директив, будет выбрана первая из них.
Параметр `off` отменяет действие унаследованных с предыдущего уровня конфигурации директив proxy_redirect.
С помощью этой директивы можно также добавлять имя хоста к относительным перенаправлениям, выдаваемым проксируемым сервером:
```nginx
proxy_redirect / /;
```
### proxy_request_buffering
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_request_buffering` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| По умолчанию | `proxy_request_buffering on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает использовать буферизацию тела запроса клиента.
| `on` | тело запроса полностью [читается](https://angie.software//angie/docs/configuration/modules/http/index.md#client-body-buffer-size) от клиента перед отправкой запроса на проксируемый сервер. |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | тело запроса отправляется на проксируемый сервер сразу же по мере его поступления. В этом случае запрос не может быть передан [следующему серверу](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream), если Angie уже начал отправку тела запроса. |
Если для отправки тела исходного запроса используется HTTP/1.1 и передача данных частями (chunked transfer encoding), то тело запроса буферизуется независимо от значения директивы, если для проксирования также не [включен](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version) HTTP/1.1.
### proxy_send_lowat
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_send_lowat` размер; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `proxy_send_lowat 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
При установке директивы в ненулевое значение Angie будет пытаться
минимизировать число операций отправки на исходящих соединениях с проксируемым
сервером либо при помощи флага `NOTE_LOWAT` метода [kqueue](https://angie.software//angie/docs/configuration/processing.md#kqueue), либо при
помощи параметра сокета `SO_SNDLOWAT`, с указанным размером.
#### NOTE
Эта директива игнорируется на Linux, Solaris и Windows.
### proxy_send_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_send_timeout` время; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `proxy_send_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при передаче запроса проксируемому серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени проксируемый сервер не примет новых данных, соединение закрывается.
### proxy_set_body
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_set_body` значение; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет переопределить тело запроса, передаваемое на проксируемый сервер. В качестве значения можно использовать текст, переменные и их комбинации.
### proxy_set_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_set_header` поле значение; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `proxy_set_header Host $proxy_host;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет переопределять или добавлять поля заголовка запроса, [передаваемые](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass-request-headers) проксируемому серверу. В качестве значения можно использовать текст, переменные и их комбинации. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы proxy_set_header. По умолчанию переопределяются только два поля:
```nginx
proxy_set_header Host $proxy_host;
proxy_set_header Connection close;
```
Если включено кэширование, поля заголовка `If-Modified-Since` , `If-Unmodified-Since` , `If-None-Match` , `If-Match` , `Range` и `If-Range` исходного запроса не передаются на проксируемый сервер.
Неизмененное поле заголовка запроса "Host" можно передать так:
```nginx
proxy_set_header Host $http_host;
```
Однако, если это поле отсутствует в заголовке запроса клиента, то ничего передаваться не будет. В этом случае лучше воспользоваться переменной [$host](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-v-host) - ее значение равно имени сервера в поле "Host" заголовка запроса, или же основному имени сервера, если поля нет:
```nginx
proxy_set_header Host $host;
```
Кроме того, можно передать имя сервера вместе с портом проксируемого сервера:
```nginx
proxy_set_header Host $host:$proxy_port;
```
Если значение поля заголовка — пустая строка, то поле вообще не будет передаваться проксируемому серверу:
```nginx
proxy_set_header Accept-Encoding "";
```
### proxy_socket_keepalive
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_socket_keepalive` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `proxy_socket_keepalive off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Конфигурирует поведение "TCP keepalive" для исходящих соединений к проксируемому серверу.
| `""` | По умолчанию для сокета действуют настройки операционной системы. |
|--------|---------------------------------------------------------------------|
| `on` | для сокета включается параметр SO_KEEPALIVE |
### proxy_ssl_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_certificate` файл [файл]; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с сертификатом в формате PEM для аутентификации на проксируемом HTTPS-сервере. В имени файла можно использовать переменные.
При включенном [proxy_ssl_ntls](#adc-proxy-ssl-ntls) директива принимает два аргумента вместо одного:
```nginx
location /proxy {
proxy_ssl_ntls on;
proxy_ssl_certificate sign.crt enc.crt;
proxy_ssl_certificate_key sign.key enc.key;
proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";
proxy_pass https://backend:443;
}
```
### proxy_ssl_certificate_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_certificate_cache` `off`;
`proxy_ssl_certificate_cache` `max=`N [`inactive=`time] [`valid=`time]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| Значение по умолчанию | `proxy_ssl_certificate_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет кэш для хранения [SSL-сертификатов](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-certificate) и [секретных ключей](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-certificate-key), заданных через переменные.
Директива поддерживает следующие параметры:
- `max` — устанавливает максимальное количество элементов в кэше. При переполнении кэша
удаляются наименее недавно использованные (LRU) элементы.
- `inactive` — определяет время, после которого элемент будет удален, если
к нему не было обращений. Значение по умолчанию — 10 секунд.
- `valid` — определяет время, в течение которого элемент кэша считается
действительным и может использоваться повторно. Значение по умолчанию — 60 секунд. По истечении этого времени
сертификаты перезагружаются или проходят повторную проверку.
- `off` — отключает кэш.
Пример:
```nginx
proxy_ssl_certificate $proxy_ssl_server_name.crt;
proxy_ssl_certificate_key $proxy_ssl_server_name.key;
proxy_ssl_certificate_cache max=1000 inactive=20s valid=1m;
```
### proxy_ssl_certificate_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_certificate_key` файл [файл]; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с секретным ключом в формате PEM для аутентификации на проксируемом HTTPS-сервере.
Вместо файла можно указать значение `engine:`name`:id`, которое загружает ключ с указанным id из OpenSSL engine с заданным именем.
Вместо файла можно указать значение `store:scheme:id`, которое используется для загрузки ключа с указанным id и URI-схемой scheme, зарегистрированной в OpenSSL provider, например [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).
В имени файла можно использовать переменные.
При включенном [proxy_ssl_ntls](#adc-proxy-ssl-ntls) директива принимает два аргумента вместо одного:
```nginx
location /proxy {
proxy_ssl_ntls on;
proxy_ssl_certificate sign.crt enc.crt;
proxy_ssl_certificate_key sign.key enc.key;
proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";
proxy_pass https://backend:443;
}
```
### proxy_ssl_ciphers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_ciphers` шифры; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `proxy_ssl_ciphers DEFAULT;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Описывает разрешенные шифры для запросов к проксируемому HTTPS-серверу. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL.
Список шифров зависит от установленной версии OpenSSL.
Полный список можно посмотреть с помощью команды `openssl ciphers`.
#### WARNING
Директива `proxy_ssl_ciphers` *не* настраивает шифры для TLS 1.3 при
использовании OpenSSL. Для настройки шифров TLS 1.3 в OpenSSL используйте
директиву [proxy_ssl_conf_command](#adc-proxy-ssl-conf-command), добавленную для расширенной
конфигурации SSL.
- В LibreSSL шифры TLS 1.3 *можно* настраивать с помощью
`proxy_ssl_ciphers`.
- В BoringSSL шифры TLS 1.3 настроить невозможно.
### proxy_ssl_conf_command
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_conf_command` имя значение; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает произвольные конфигурационные [команды](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) OpenSSL при установлении соединения с проксируемым HTTPS-сервером.
#### NOTE
Директива поддерживается при использовании OpenSSL 1.0.2 и выше.
Чтобы настроить шифры TLS 1.3 в OpenSSL, используйте команду `ciphersuites`.
На одном уровне может быть указано несколько директив proxy_ssl_conf_command. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы proxy_ssl_conf_command.
#### WARNING
Следует учитывать, что изменение настроек OpenSSL напрямую может привести к неожиданному поведению.
### proxy_ssl_crl
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_crl` файл; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Указывает файл с отозванными сертификатами (CRL) в формате PEM, используемыми при [проверке](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-verify) сертификата проксируемого HTTPS-сервера.
### proxy_ssl_name
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_name` имя; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `proxy_ssl_name $proxy_host;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет переопределить имя сервера, используемое при [проверке](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-verify) сертификата проксируемого HTTPS-сервера, а также для [передачи его через SNI](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-server-name) при установлении соединения с проксируемым HTTPS-сервером.
По умолчанию используется имя хоста из URL'а, заданного директивой [proxy_pass](#adc-proxy-pass).
### proxy_ssl_ntls
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_ntls` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `proxy_ssl_ntls off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Включает клиентскую поддержку NTLS при использовании TLS библиотеки [TongSuo](https://github.com/Tongsuo-Project/Tongsuo).
```nginx
location /proxy {
proxy_ssl_ntls on;
proxy_ssl_certificate sign.crt enc.crt;
proxy_ssl_certificate_key sign.key enc.key;
proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";
proxy_pass https://backend:443;
}
```
#### NOTE
Angie необходимо собрать с использованием параметра конфигурации `--with-ntls`, с соответствующей SSL библиотекой с поддержкой NTLS
```default
./configure --with-openssl=../Tongsuo-8.3.0 \
--with-openssl-opt=enable-ntls \
--with-ntls
```
### proxy_ssl_password_file
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_password_file` файл; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с паролями от [секретных ключей](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-certificate-key), где каждый пароль указан на отдельной строке. Пароли применяются по очереди в момент загрузки ключа.
### proxy_ssl_protocols
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`]; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| По умолчанию | `proxy_ssl_protocols TLSv1.2 TLSv1.3;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает указанные протоколы для запросов к проксируемому HTTPS-серверу.
### proxy_ssl_server_name
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_server_name` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `proxy_ssl_server_name off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает передачу имени сервера,
заданного директивой [proxy_ssl_name](#adc-proxy-ssl-name),
через расширение
[Server Name Indication](http://en.wikipedia.org/wiki/Server_Name_Indication)
протокола TLS
(SNI,
[RFC 6066](https://datatracker.ietf.org/doc/html/rfc6066.html))
при установлении соединения с проксируемым HTTPS-сервером.
### proxy_ssl_session_reuse
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_session_reuse` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------------|
| По умолчанию | `proxy_ssl_session_reuse on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, использовать ли повторно SSL-сессии при работе с проксируемым сервером. Если в логах появляются ошибки "SSL3_GET_FINISHED:digest check failed", то можно попробовать выключить повторное использование сессий.
### proxy_ssl_trusted_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_trusted_certificate` файл; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает файл с доверенными сертификатами CA в формате PEM, используемыми при [проверке](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-verify) сертификата проксируемого HTTPS-сервера.
### proxy_ssl_verify
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_verify` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `proxy_ssl_verify off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает проверку сертификата проксируемого HTTPS-сервера.
### proxy_ssl_verify_depth
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_verify_depth` число; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `proxy_ssl_verify_depth 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Устанавливает глубину проверки в цепочке сертификатов проксируемого HTTPS-сервера.
### proxy_store
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_store` `on` | `off` | строка; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `proxy_store off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает сохранение на диск файлов.
| `on` | сохраняет файлы в соответствии с путями, указанными в директивах [alias](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-alias) или [root](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-root) |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | запрещает сохранение файлов |
Имя файла можно задать явно с помощью `строки` с переменными:
```nginx
proxy_store /data/www$original_uri;
```
Время изменения файлов выставляется согласно полученному полю `Last-Modified` в заголовке ответа. Ответ сначала записывается во временный файл, а потом этот файл переименовывается. Временный файл и постоянное место хранения ответа могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешевой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой системе, что и каталог с временными файлами, задаваемый директивой [proxy_temp_path](#adc-proxy-temp-path) для данного location.
Директиву можно использовать для создания локальных копий статических неизменяемых файлов, например, так:
```nginx
location /images/ {
root /data/www;
error_page 404 = /fetch$uri;
}
location /fetch/ {
internal;
proxy_pass http://backend/;
proxy_store on;
proxy_store_access user:rw group:rw all:r;
proxy_temp_path /data/temp;
alias /data/www/;
}
```
или так:
```nginx
location /images/ {
root /data/www;
error_page 404 = @fetch;
}
location @fetch {
internal;
proxy_pass http://backend;
proxy_store on;
proxy_store_access user:rw group:rw all:r;
proxy_temp_path /data/temp;
root /data/www;
}
```
### proxy_store_access
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_store_access` пользователи:права ...; |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| По умолчанию | `proxy_store_access user:rw;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает права доступа для создаваемых файлов и каталогов, например,
```nginx
proxy_store_access user:rw group:rw all:r;
```
Если заданы какие-либо права для group или all, то права для user указывать необязательно:
```nginx
proxy_store_access group:rw all:r;
```
### proxy_temp_file_write_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_temp_file_write_size` размер; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `proxy_temp_file_write_size 8k|16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает размер данных, сбрасываемых во временный файл за один раз, при включенной буферизации ответов проксируемого сервера во временные файлы. По умолчанию размер ограничен двумя буферами, заданными директивами [proxy_buffer_size](#adc-proxy-buffer-size) и [proxy_buffers](#adc-proxy-buffers). Максимальный размер временного файла задается директивой [proxy_max_temp_file_size](#adc-proxy-max-temp-file-size).
### proxy_temp_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_temp_path` путь [уровень1 [уровень2 [уровень3]]]\`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `proxy_temp_path proxy_temp;`
(путь зависит от [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-proxy-temp-path`) |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает имя каталога для хранения временных файлов с данными, полученными от проксируемых серверов. В каталоге может использоваться иерархия подкаталогов до трех уровней. Например, при такой конфигурации
```nginx
proxy_temp_path /spool/angie/proxy_temp 1 2;
```
временный файл будет следующего вида:
```nginx
/spool/angie/proxy_temp/7/45/00000123457
```
См. также параметр use_temp_path директивы [proxy_cache_path](#adc-proxy-cache-path).
## Встроенные переменные
В модуле http_proxy есть встроенные переменные, которые можно использовать для формирования заголовков с помощью директивы [proxy_set_header](#adc-proxy-set-header):
### `$proxy_host`
имя и порт проксируемого сервера, как указано в директиве [proxy_pass](#adc-proxy-pass);
### `$proxy_port`
порт проксируемого сервера, как указано в директиве [proxy_pass](#adc-proxy-pass), или стандартный порт протокола;
### `$proxy_add_x_forwarded_for`
поле заголовка запроса клиента `X-Forwarded-For` и добавленная к нему через запятую переменная [$remote_addr](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-v-remote-addr). Если же поля `X-Forwarded-For` в заголовке запроса клиента нет, то переменная [$proxy_add_x_forwarded_for](#adc-v-proxy-add-x-forwarded-for) равна переменной [$remote_addr](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-v-remote-addr).
# https://angie.software/adc/docs/load_balancer/reference/http/http_random_index.md
# Random Index
Обслуживает запросы, оканчивающиеся косой чертой (`/`), и выдает случайный файл в качестве индексного файла каталога. Модуль выполняется до модуля `http_index`.
## Пример конфигурации
```nginx
location / {
random_index on;
}
```
## Директивы
### random_index
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `random_index` `on` | `off`.; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `random_index off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Разрешает или запрещает в содержащем эту директиву `location` обработку этим модулем.
# https://angie.software/adc/docs/load_balancer/reference/http/http_realip.md
# RealIP
Позволяет менять адрес и необязательный порт клиента на переданные в указанном поле заголовка.
## Пример конфигурации
```nginx
set_real_ip_from 192.168.1.0/24;
set_real_ip_from 192.168.2.1;
set_real_ip_from 2001:0db8::/32;
real_ip_header X-Forwarded-For;
real_ip_recursive on;
```
## Директивы
### set_real_ip_from
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `set_real_ip_from` адрес | CIDR | `unix`:; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает доверенные адреса, которые передают верный адрес для замены. Если указано специальное значение `unix:`, доверенными будут считаться все UNIX-сокеты. Доверенные адреса могут быть также заданы при помощи имени хоста.
### real_ip_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `real_ip_header` поле | `X-Real-IP` | `X-Forwarded-For` | `proxy_protocol`; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
| По умолчанию | `real_ip_header X-Real-IP;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает поле заголовка запроса, значение которого будет использоваться для замены адреса клиента.
Значение поля заголовка запроса, содержащее необязательный порт, также используется для замены порта клиента. Адрес и порт должны быть указаны согласно [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986).
Параметр `proxy_protocol` меняет адрес клиента на указанный в заголовке PROXY-протокола. Протокол PROXY должен быть предварительно включен при помощи установки параметра proxy_protocol в директиве [listen](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-listen).
### real_ip_recursive
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `real_ip_recursive` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `real_ip_recursive off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
При выключенном рекурсивном поиске исходный адрес клиента, совпадающий с одним из доверенных адресов, заменяется на последний адрес, переданный в поле заголовка запроса, заданного директивой [real_ip_header](#adc-real-ip-header). При включенном рекурсивном поиске исходный адрес клиента, совпадающий с одним из доверенных адресов, заменяется на последний не доверенный адрес, переданный в заданном поле заголовка запроса.
## Встроенные переменные
### `$realip_remote_addr`
хранит исходный адрес клиента
### `$realip_remote_port`
хранит исходный порт клиента
# https://angie.software/adc/docs/load_balancer/reference/http/http_referer.md
# Referer
Позволяет блокировать доступ к сайту для запросов с неверными значениями поля `Referer` в заголовке. Следует иметь в виду, что подделать запрос с нужным значением поля `Referer` не составляет большого труда, поэтому цель использования данного модуля заключается не в стопроцентном блокировании подобных запросов, а в блокировании массового потока запросов, сделанных обычными браузерами. Нужно также учитывать, что обычные браузеры могут не передавать поле `Referer` даже для верных запросов.
## Пример конфигурации
```nginx
valid_referers none blocked server_names
*.example.com example.* www.example.org/galleries/
~\.google\.;
if ($invalid_referer) {
return 403;
}
```
## Директивы
### referer_hash_bucket_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `referer_hash_bucket_size` размер; |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию | `referer_hash_bucket_size 64;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location |
Задает размер корзины хэш-таблиц со значениями `Referer`. Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
### referer_hash_max_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `referer_hash_max_size` размер; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `referer_hash_max_size 2048;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location |
Задает максимальный размер хэш-таблиц со значениями `Referer`. Подробнее настройка хэш-таблиц обсуждается [отдельно](https://angie.software//angie/docs/configuration/configfile.md#configure-hashes).
### valid_referers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `valid_referers` `none` | `blocked` | `server_names` | строка ...; |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location |
Задает значения поля `Referer` заголовка запроса, при которых встроенная переменная [$invalid_referer](#adc-v-invalid-referer) будет иметь пустую строку в качестве значения. В противном случае значение переменной равно "1". Поиск совпадения производится без учета регистра символов.
Параметры могут быть следующие:
| `none` | поле `Referer` в заголовке запроса отсутствует; |
|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `blocked` | поле `Referer` в заголовке запроса присутствует, но его значение удалено межсетевым экраном (firewall) или прокси-сервером; к таким значениям относятся строки, не начинающиеся на "`http://`" или "`https://`"; |
| `server_names` | в поле `Referer` заголовка запроса указано одно из имен сервера; |
| `произвольная строка` | задает имя сервера и необязательное начало URI. В начале или конце имени сервера может быть "\*". При проверке порт сервера в поле `Referer` игнорируется; |
| `регулярное выражение` | в начале должен быть символ "~". Необходимо учитывать, что на совпадение с выражением будет проверяться текст, начинающийся после "`http://`" или "`https://`". |
Пример:
```nginx
valid_referers none blocked server_names
*.example.com example.* www.example.org/galleries/
~\.google\.;
```
## Встроенные переменные
### `$invalid_referer`
Пустая строка, если значение поля `Referer` заголовка запроса считается [правильным](https://angie.software//angie/docs/configuration/modules/http/http_referer.md#valid-referers), иначе "1".
# https://angie.software/adc/docs/load_balancer/reference/http/http_rewrite.md
# Rewrite
Позволяет изменять URI запроса с помощью регулярных выражений PCRE, делать перенаправления и выбирать конфигурацию по условию.
Директивы [break](#adc-break), [if](#adc-if), [return](#adc-return), [rewrite](#adc-rewrite) и [set](#adc-set) обрабатываются в следующем порядке:
* последовательно выполняются директивы этого модуля, описанные на уровне `server`;
* в цикле:
> * ищется `location` по URI запроса;
> * последовательно выполняются директивы этого модуля, описанные в найденном `location`;
> * цикл повторяется, если URI запроса [изменялся](https://angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5), но [не более](https://angie.software//angie/docs/configuration/modules/http/index.md#internal) 10 раз.
## Директивы
### break
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `break`; |
|------------------------------------------------------------------------------------------|----------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location, if |
Завершает обработку текущего набора директив модуля `http_rewrite`.
Если директива указана внутри `location`, дальнейшая обработка запроса продолжается в этом `location`.
Пример:
```nginx
if ($slow) {
limit_rate 10k;
break;
}
```
### if
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `if` (условие) { ... } |
|------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location |
Проверяется указанное условие. Если оно истинно, то выполняются указанные в фигурных скобках директивы этого модуля и запросу назначается конфигурация, указанная внутри директивы `if`. Конфигурации внутри директив `if` наследуются с предыдущего уровня конфигурации.
#### WARNING
Хотя внутри блока `if` можно применять директивы других модулей,
делать это не рекомендуется,
так как это может привести к непредвиденному поведению.
В качестве условия могут быть заданы:
* имя переменной; ложными значениями переменной являются пустая строка или "0";
* сравнение переменной со строкой с помощью операторов "=" и "!=";
* соответствие переменной регулярному выражению с учетом регистра символов — "~" и без него — "~\*". В регулярных выражениях можно использовать группы захвата, которые затем доступны в виде переменных $1..$9. Также можно использовать отрицательные операторы "!~" и "!~\*". Если в регулярном выражении встречаются символы "}" или ";", то все выражение следует заключить в одинарные или двойные кавычки.
* проверка существования файла с помощью операторов "-f" и "!-f";
* проверка существования каталога с помощью операторов "-d" и "!-d";
* проверка существования файла, каталога или символической ссылки с помощью операторов "-e" и "!-e";
* проверка исполняемости файла с помощью операторов "-x" и "!-x".
Примеры:
```nginx
if ($http_user_agent ~ MSIE) {
rewrite ^(.*)$ /msie/$1 break;
}
if ($http_cookie ~* "id=([^;]+)(?:;|$)") {
set $id $1;
}
if ($request_method = POST) {
return 405;
}
if ($slow) {
limit_rate 10k;
}
if ($invalid_referer) {
return 403;
}
```
#### NOTE
Значение встроенной переменной [$invalid_referer](https://angie.software//adc/docs/load_balancer/reference/http/http_referer.md#adc-v-invalid-referer) задается директивой [valid_referers](https://angie.software//adc/docs/load_balancer/reference/http/http_referer.md#adc-valid-referers).
### return
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `return` код [текст];
`return` код URL;
`return` URL; |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location, if |
Завершает обработку и возвращает клиенту указанный `код`. Нестандартный
код 444 закрывает соединение без передачи заголовка ответа.
Можно задать либо URL перенаправления (для кодов 301, 302, 303, 307 и 308) либо текст тела ответа (для остальных кодов). В тексте тела ответа и URL перенаправления можно использовать переменные. Как частный случай, URL перенаправления может быть задан как URI, локальный для данного сервера, при этом полный URL перенаправления формируется согласно схеме запроса ($scheme) и директивам [server_name_in_redirect](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-server-name-in-redirect) и [port_in_redirect](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-port-in-redirect).
Кроме того, в качестве единственного параметра можно указать URL для временного перенаправления с кодом 302. Такой параметр должен начинаться со строк `http://`, `https://` или "$scheme". В URL можно использовать переменные.
См. также директиву [error_page](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-error-page).
### rewrite
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `rewrite` regex замена [флаг]; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location, if |
Если указанное регулярное выражение regex соответствует URI запроса, URI
изменяется в соответствии со строкой замены. Директивы `rewrite`
выполняются последовательно, в порядке их следования в конфигурационном файле. С
помощью флага можно прекратить дальнейшую обработку директив. Если строка
замены начинается с `http://`, `https://` или `$scheme`, то
обработка завершается и клиенту возвращается перенаправление.
Необязательный параметр флаг может быть задан одним из следующих значений:
| `last` | завершает обработку текущего набора директив модуля `http_rewrite`, после чего ищется новый `location`, соответствующий измененному URI; |
|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| `break` | завершает обработку текущего набора директив модуля `http_rewrite` аналогично директиве `break`; |
| `redirect` | возвращает временное перенаправление с кодом 302; используется, если
строка `замены` не начинается с `http://`, `https://` или
"$scheme"; |
| `permanent` | возвращает постоянное перенаправление с кодом 301. |
Полный URL перенаправлений формируется согласно схеме запроса ($scheme) и директив [server_name_in_redirect](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-server-name-in-redirect) и [port_in_redirect](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-port-in-redirect).
Пример:
```nginx
server {
# ...
rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last;
rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra last;
return 403;
# ...
}
```
Если же эти директивы поместить в location "/download/", то нужно заменить флаг `last` на `break`, иначе Angie сделает 10 циклов и вернет ошибку 500:
```nginx
location /download/ {
rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra break;
return 403;
}
```
Если в строке `замены` указаны новые аргументы запроса, то предыдущие
аргументы запроса добавляются после них. Если такое поведение нежелательно,
можно отказаться от этого добавления, указав в конце строки замены знак вопроса,
например:
```nginx
rewrite ^/users/(.*)$ /show?user=$1? last;
```
Если в регулярном выражении встречаются символы "}" или ";", то все выражение следует заключить в одинарные или двойные кавычки.
### rewrite_log
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `rewrite_log` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `rewrite_log off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if |
Разрешает или запрещает записывать в [error_log](https://angie.software//adc/docs/load_balancer/reference/core.md#adc-error-log) на уровне `notice` результаты обработки директив модуля `http_rewrite`.
### set
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `set` $переменная значение; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location, if |
Устанавливает значение указанной переменной. В качестве значения можно использовать текст, переменные и их комбинации.
### uninitialized_variable_warn
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `uninitialized_variable_warn` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| По умолчанию | `uninitialized_variable_warn on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if |
Определяет, нужно ли писать в лог предупреждения о неинициализированных переменных.
## Внутреннее устройство
Директивы модуля `http_rewrite` компилируются на стадии конфигурации во внутренние инструкции, интерпретируемые во время обработки запроса. Интерпретатор представляет из себя простую стековую виртуальную машину.
Например, директивы
```nginx
location /download/ {
if ($forbidden) {
return 403;
}
if ($slow) {
limit_rate 10k;
}
rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
}
```
будут транслированы в такие инструкции:
```console
переменная $forbidden
проверка на ноль
возврат 403
завершение всего кода
переменная $slow
проверка на ноль
проверка регулярного выражения
копирование "/"
копирование $1
копирование "/mp3/"
копирование $2
копирование ".mp3"
завершение регулярного выражения
завершение всего кода
```
Обратите внимание, что инструкций для директивы [limit_rate](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-limit-rate) нет, поскольку она не имеет отношения к модулю `http_rewrite`. Для блока `if` создается отдельная конфигурация. Если условие истинно, запрос получает эту конфигурацию, и в ней `limit_rate` равен 10k.
Директиву
```nginx
rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
```
можно сделать на одну инструкцию меньше, если в регулярном выражении перенести первую косую черту внутрь скобок:
```nginx
rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
```
Тогда соответствующие инструкции будут выглядеть так:
```console
проверка регулярного выражения
копирование $1
копирование "/mp3/"
копирование $2
копирование ".mp3"
завершение регулярного выражения
завершение всего кода
```
# https://angie.software/adc/docs/load_balancer/reference/http/http_scgi.md
# SCGI
Позволяет передавать запросы SCGI-серверу.
## Пример конфигурации
```nginx
location / {
include scgi_params;
scgi_pass localhost:9000;
}
```
## Директивы
### scgi_bind
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_bind` адрес [`transparent`] | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает локальный IP-адрес с необязательным портом, который будет использоваться в исходящих соединениях с SCGI-сервером. В значении параметра допустимо использование переменных. Специальное значение `off` отменяет действие унаследованной с предыдущего уровня конфигурации директивы scgi_bind, позволяя системе самостоятельно выбирать локальный IP-адрес и порт.
Параметр `transparent` позволяет задать нелокальный IP-адрес, который будет использоваться в исходящих соединениях с SCGI-сервером, например, реальный IP-адрес клиента:
```nginx
scgi_bind $remote_addr transparent;
```
Для работы параметра обычно требуется запустить рабочие процессы Angie с привилегиями [суперпользователя](https://angie.software//angie/docs/configuration/modules/core.md#user). В Linux это не требуется, так как если указан параметр transparent, то рабочие процессы наследуют capability CAP_NET_RAW из главного процесса.
#### NOTE
Необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с SCGI-сервера.
### scgi_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_buffer_size` размер; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `scgi_buffer_size 4k|8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает размер буфера, в который будет читаться первая часть ответа, получаемого от SCGI-сервера. В этой части ответа обычно находится небольшой заголовок ответа. По умолчанию размер одного буфера равен размеру страницы памяти. В зависимости от платформы это или 4K, или 8K, однако его можно сделать меньше.
### scgi_buffering
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_buffering` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `scgi_buffering on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает использовать буферизацию ответов SCGI-сервера.
| `on` | Angie принимает ответ SCGI-сервера как можно быстрее, сохраняя его в
буферы, заданные директивами [scgi_buffer_size](#adc-scgi-buffer-size) и
[scgi_buffers](#adc-scgi-buffers). Отправка клиенту при этом выполняется параллельно:
заполненные буферы передаются на отправку, но
суммарно не более значения [scgi_busy_buffers_size](#adc-scgi-busy-buffers-size). Если буфер
заполнен не полностью, то на отправку он не передается, если только это
не последние данные ответа. Поэтому для моментальной передачи каждых
нескольких байт режим буферизированного чтения не подходит. Если ответ
не вмещается целиком в память, то его часть может быть записана на диск
во [временный файл](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-temp-path). Запись во временные файлы
контролируется директивами [scgi_max_temp_file_size](#adc-scgi-max-temp-file-size) и
[scgi_temp_file_write_size](#adc-scgi-temp-file-write-size). |
|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | Ответ передается клиенту сразу же по мере его поступления. Angie
работает в цикле «прочитал — отправил» и не ждет, пока буфер заполнится
целиком: например, прочитанные 10 байт из буфера 4К будут сразу
отправлены клиенту. При этом если весь ответ умещается в буфер, Angie
может прочитать его целиком. Максимальный размер данных, который Angie
может принять от сервера за один раз, задается директивой
[scgi_buffer_size](#adc-scgi-buffer-size). При `off` не работает
[scgi_limit_rate](#adc-scgi-limit-rate). |
Буферизация может быть также включена или выключена путем передачи значения "yes" или "no" в поле `X-Accel-Buffering` заголовка ответа. Эту возможность можно запретить с помощью директивы [scgi_ignore_headers](#adc-scgi-ignore-headers).
### scgi_buffers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_buffers` число размер; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `scgi_buffers 8 4k | 8k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число и размер буферов для одного соединения, в которые будет читаться ответ, получаемый от SCGI-сервера.
По умолчанию размер одного буфера равен размеру страницы. В зависимости от платформы это или 4K, или 8K.
### scgi_busy_buffers_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_busy_buffers_size` размер; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `scgi_busy_buffers_size 8k | 16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
При включенной [буферизации](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-buffering) ответов SCGI-сервера, ограничивает суммарный размер буферов, которые могут быть заняты для отправки ответа клиенту, пока ответ еще не прочитан целиком. Оставшиеся буферы тем временем могут использоваться для чтения ответа и, при необходимости, буферизации части ответа во временный файл.
По умолчанию размер ограничен величиной двух буферов, заданных директивами [scgi_buffer_size](#adc-scgi-buffer-size) и [scgi_buffers](#adc-scgi-buffers).
### scgi_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache` зона | `off`; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `scgi_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает зону разделяемой памяти, используемой для кэширования. Одна и та же зона может использоваться в нескольких местах. В значении параметра можно использовать переменные.
| `off` | запрещает кэширование, унаследованное с предыдущего уровня конфигурации. |
|---------|----------------------------------------------------------------------------|
### scgi_cache_background_update
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_background_update` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| По умолчанию | `scgi_cache_background_update off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запустить фоновый подзапрос для обновления просроченного элемента кэша, в то время как клиенту возвращается устаревший кэшированный ответ.
#### WARNING
Использование устаревшего кэшированного ответа в момент его обновления должно быть [разрешено](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-cache-use-stale-updating).
### scgi_cache_bypass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_bypass` ...; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает условия, при которых ответ не будет браться из кэша. Если значение хотя бы одного из строковых параметров непустое и не равно "0", то ответ не берется из кэша:
```nginx
scgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
scgi_cache_bypass $http_pragma $http_authorization;
```
Можно использовать совместно с директивой [scgi_no_cache](#adc-scgi-no-cache).
### scgi_cache_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_key` строка; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает ключ для кэширования, например,
```nginx
scgi_cache_key localhost:9000$request_uri;
```
### scgi_cache_lock
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_lock` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `scgi_cache_lock off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если включено, одновременно только одному запросу будет позволено заполнить новый элемент кэша, идентифицируемый согласно директиве [scgi_cache_key](#adc-scgi-cache-key), передав запрос на SCGI-сервер. Остальные запросы этого же элемента будут либо ожидать появления ответа в кэше, либо освобождения блокировки этого элемента, в течение времени, заданного директивой [scgi_cache_lock_timeout](#adc-scgi-cache-lock-timeout).
### scgi_cache_lock_age
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_lock_age` время; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `scgi_cache_lock_age 5s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если последний запрос, переданный на SCGI-сервер для заполнения нового элемента кэша, не завершился за указанное время, на SCGI-сервер может быть передан еще один запрос.
### scgi_cache_lock_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_lock_timeout` время; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `scgi_cache_lock_timeout 5s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут для [scgi_cache_lock](#adc-scgi-cache-lock). По истечении указанного времени запрос будет передан на SCGI-сервер, однако ответ не будет кэширован.
### scgi_cache_max_range_offset
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_max_range_offset` число; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает смещение в байтах для запросов с указанием диапазона запрашиваемых байт (byte-range requests). Если диапазон находится за указанным смещением, range-запрос будет передан на SCGI-сервер и ответ не будет кэширован.
### scgi_cache_methods
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_methods` `GET` | `HEAD` | `POST` ...; |
|------------------------------------------------------------------------------------------|-----------------------------------------------------|
| По умолчанию | `scgi_cache_methods GET HEAD;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если метод запроса клиента указан в этой директиве, то ответ будет кэширован. Методы "GET" и "HEAD" всегда добавляются в список, но тем не менее рекомендуется перечислять их явно. См. также директиву [scgi_no_cache](#adc-scgi-no-cache).
### scgi_cache_min_uses
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_min_uses` число; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `scgi_cache_min_uses 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает число запросов, после которого ответ будет кэширован.
#### WARNING
Метаданные кэша хранятся в разделяемой памяти. Ручное удаление файлов кэша не
сбрасывает счетчики и может привести к непредсказуемому поведению. Для
полного сброса остановите сервер, удалите директорию кэша и запустите снова.
#### NOTE
Сторонние модули очистки кэша (например, [Cache Purge](https://angie.software//angie/docs/installation/external-modules/cache-purge.md#external-cache-purge)) удаляют только
файлы, но не сбрасывают счетчик scgi_cache_min_uses. Директива
предназначена для защиты кэша от загрязнения редкими запросами, и сброс
счетчика при очистке может негативно повлиять на производительность.
### scgi_cache_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_path` путь [`levels=`уровни] [`use_temp_path=``on` | `off`] `keys_zone=`имя:размер [`inactive=`время] [`max_size=`размер] [`min_free=`размер] [`manager_files=`число] [`manager_sleep=`время] [`manager_threshold=`время] [`loader_files=`число] [`loader_sleep=`время] [`loader_threshold=`время]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Задает путь и другие параметры кэша. Данные кэша хранятся в файлах. Именем файла в кэше является результат функции MD5 от [ключа кэширования](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-cache-key).
Параметр `levels` задает уровни иерархии кэша: можно задать от 1 до 3 уровней, на каждом уровне допускаются значения 1 или 2.
Например, при использовании
```nginx
scgi_cache_path /data/angie/cache levels=1:2 keys_zone=one:10m;
```
имена файлов в кэше будут такого вида:
```nginx
/data/angie/cache/c/29/b7f54b2df7773722d382f4809d65029c
```
Кэшируемый ответ сначала записывается во временный файл, а потом этот файл переименовывается. Временные файлы и кэш могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешевой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если кэш будет находиться на той же файловой системе, что и каталог с временными файлами.
Какой из каталогов будет использоваться для временных файлов, определяется параметром `use_temp_path`.
| `on` | Если параметр не задан или установлен в значение "on", будет использоваться каталог, задаваемый директивой [scgi_temp_path](#adc-scgi-temp-path) для данного location |
|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | временные файлы будут располагаться непосредственно в каталоге кэша |
Кроме того, все активные ключи и информация о данных хранятся в зоне разделяемой памяти, имя и размер которой задаются параметром `keys_zone`. Зоны размером в 1 мегабайт достаточно для хранения около 8 тысяч ключей. Метаданные кэша хранятся в разделяемой памяти.
Если к данным кэша не обращаются в течение времени, заданного параметром `inactive`, то данные удаляются, независимо от их свежести.
По умолчанию `inactive` равен 10 минутам.
Специальный процесс **менеджера кэша** следит за максимальным размером кэша, а также за минимальным объемом свободного места на файловой системе с кэшем, и удаляет наименее востребованные данные при превышении максимального размера кэша или недостаточном объеме свободного места. Удаление данных происходит итерациями.
| `max_size` | максимальное пороговое значение размера кэша |
|---------------------|--------------------------------------------------------------------------------------------------------|
| `min_free` | минимальное пороговое значение объема свободного места на файловой системе с кэшем |
| `manager_files` | максимальное количество удаляемых элементов кэша за одну итерацию
По умолчанию: `100` |
| `manager_threshold` | ограничивает время работы одной итерации
По умолчанию: `200` миллисекунд |
| `manager_sleep` | время, в течение которого выдерживается пауза между итерациями
По умолчанию: `50` миллисекунд |
Через минуту после старта Angie активируется специальный процесс **загрузчика кэша**, который загружает в зону кэша информацию о ранее кэшированных данных, хранящихся на файловой системе. Загрузка также происходит итерациями.
| `loader_files` | максимальное количество элементов кэша к загрузке в одну итерацию
По умолчанию: `100` |
|--------------------|--------------------------------------------------------------------------------------------------------|
| `loader_threshold` | ограничивает время работы одной итерации
По умолчанию: `200` миллисекунд |
| `loader_sleep` | время, в течение которого выдерживается пауза между итерациями
По умолчанию: `50` миллисекунд |
### scgi_cache_revalidate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_revalidate` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `scgi_cache_revalidate off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает ревалидацию просроченных элементов кэша при помощи условных запросов с полями заголовка `If-Modified-Since` и `If-None-Match` .
### scgi_cache_use_stale
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_use_stale` `error` | `timeout` | `invalid_header` | `updating` | `http_500` | `http_503` | `http_403` | `http_404` | `http_429` | `off` ...; |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `scgi_cache_use_stale off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, в каких случаях можно использовать устаревший кэшированный ответ. Параметры директивы совпадают с параметрами директивы [scgi_next_upstream](#adc-scgi-next-upstream).
| `error` | Позволяет использовать устаревший кэшированный ответ при невозможности выбора SCGI-сервера для обработки запроса. |
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `updating` | Дополнительный параметр, разрешает использовать устаревший кэшированный ответ, если на данный момент он уже обновляется. Это позволяет минимизировать число обращений к SCGI-серверам при обновлении кэшированных данных. |
Использование устаревшего кэшированного ответа может также быть разрешено непосредственно в заголовке ответа на определенное количество секунд после того, как ответ устарел:
* Расширение [stale-while-revalidate](https://datatracker.ietf.org/doc/html/rfc5861#section-3) поля заголовка `Cache-Control` разрешает использовать устаревший кэшированный ответ, если на данный момент он уже обновляется.
* Расширение [stale-if-error](https://datatracker.ietf.org/doc/html/rfc5861#section-4) поля заголовка `Cache-Control` разрешает использовать устаревший кэшированный ответ в случае ошибки.
#### NOTE
Такой способ менее приоритетен, чем задание параметров директивы.
Чтобы минимизировать число обращений к SCGI-серверам при заполнении нового элемента кэша, можно воспользоваться директивой [scgi_cache_lock](#adc-scgi-cache-lock).
### scgi_cache_valid
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_cache_valid` [код ...] время; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает время кэширования для разных кодов ответа. Например, директивы
```nginx
scgi_cache_valid 200 302 10m;
scgi_cache_valid 404 1m;
```
задают время кэширования 10 минут для ответов с кодами 200 и 302 и 1 минуту для ответов с кодом 404.
Если указано только время кэширования,
```nginx
scgi_cache_valid 5m;
```
то кэшируются только ответы 200, 301 и 302.
Кроме того, можно кэшировать любые ответы с помощью параметра `any`:
```nginx
scgi_cache_valid 200 302 10m;
scgi_cache_valid 301 1h;
scgi_cache_valid any 1m;
```
#### NOTE
Параметры кэширования могут также быть заданы непосредственно в заголовке ответа. Такой способ приоритетнее, чем задание времени кэширования с помощью директивы.
* Поле заголовка `X-Accel-Expires` задает время кэширования ответа в секундах. Значение 0 запрещает кэшировать ответ. Если значение начинается с префикса @, оно задает абсолютное время в секундах с начала эпохи, до которого ответ может быть кэширован.
* Если в заголовке нет поля `X-Accel-Expires`, параметры кэширования определяются по полям заголовка `Expires` или `Cache-Control`.
* Ответ, в заголовке которого есть поле `Set-Cookie`, не будет кэшироваться.
* Ответ, в заголовке которого есть поле `Vary` со специальным значением "\*", не будет кэшироваться. Ответ, в заголовке которого есть поле `Vary` с другим значением, будет кэширован с учетом соответствующих полей заголовка запроса.
Обработка одного или более из этих полей заголовка может быть отключена при помощи директивы [scgi_ignore_headers](#adc-scgi-ignore-headers).
### scgi_connect_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_connect_timeout` время; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `scgi_connect_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут для установления соединения с SCGI-сервером. Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.
### scgi_connection_drop
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_connection_drop` время | `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------------|
| По умолчанию | `scgi_connection_drop off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Настраивает завершение всех соединений с проксируемым сервером,
если он был удален из группы или помечен как постоянно недоступный
в результате процесса [reresolve](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve)
или [команды API](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods) `DELETE`.
Соединение завершается, когда обрабатывается следующее событие чтения или записи
для клиента или проксируемого сервера.
Установка времени включает [таймаут](https://angie.software//angie/docs/configuration/configfile.md#syntax) до завершения соединения;
при выборе значения `on` соединения завершаются немедленно.
### scgi_force_ranges
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_force_ranges` `off`; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `scgi_force_ranges off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Включает поддержку диапазонов запрашиваемых байт (byte-range) для кэшированных и некэшированных ответов SCGI-сервера вне зависимости от наличия поля `Accept-Ranges` в заголовках этих ответов.
### scgi_hide_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_hide_header` поле; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
По умолчанию Angie не передает клиенту поля заголовка `Status` и `X-Accel-...` из ответа SCGI-сервера. Директива scgi_hide_header задает дополнительные поля, которые не будут передаваться. Если же передачу полей нужно разрешить, можно воспользоваться директивой [scgi_pass_header](#adc-scgi-pass-header).
### scgi_ignore_client_abort
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_ignore_client_abort` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `scgi_ignore_client_abort off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, закрывать ли соединение с SCGI-сервером в случае, если клиент закрыл соединение, не дождавшись ответа.
### scgi_ignore_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_ignore_headers` поле ...; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Запрещает обработку некоторых полей заголовка из ответа SCGI-сервера. В директиве можно указать поля `X-Accel-Redirect`, `X-Accel-Expires`, `X-Accel-Limit-Rate`, `X-Accel-Buffering`, `X-Accel-Charset`, `Expires`, `Cache-Control`, `Set-Cookie` и `Vary`.
Если не запрещено, обработка этих полей заголовка заключается в следующем:
* `X-Accel-Expires`, `Expires`, `Cache-Control`, `Set-Cookie` и `Vary` задают [параметры кэширования](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-cache-valid) ответа;
* `X-Accel-Redirect` производит [внутреннее перенаправление](https://angie.software//angie/docs/configuration/modules/http/index.md#internal) на указанный URI;
* `X-Accel-Limit-Rate` задает [ограничение скорости](https://angie.software//angie/docs/configuration/modules/http/index.md#limit-rate) передачи ответа клиенту;
* `X-Accel-Buffering` включает или выключает [буферизацию](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-buffering) ответа;
* `X-Accel-Charset` задает желаемую [кодировку](https://angie.software//angie/docs/configuration/modules/http/http_charset.md#id3) ответа.
### scgi_intercept_errors
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_intercept_errors` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `scgi_intercept_errors off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, передавать ли клиенту ответы SCGI-сервера с кодом больше либо равным 300, или же перехватывать их и перенаправлять на обработку Angie с помощью директивы [error_page](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-error-page).
### scgi_limit_rate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_limit_rate` скорость; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | `scgi_limit_rate 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает скорость чтения ответа от SCGI-сервера.
Скорость задается в байтах в секунду; можно использовать переменные.
| `0` | отключает ограничение скорости |
|-------|----------------------------------|
#### NOTE
Ограничение устанавливается на запрос, поэтому, если Angie одновременно откроет два соединения к SCGI-серверу, суммарная скорость будет вдвое выше заданного ограничения. Ограничение работает только в случае, если включена [буферизация](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-buffering) ответов SCGI-сервера.
### scgi_max_temp_file_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_max_temp_file_size` размер; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `scgi_max_temp_file_size 1024m;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Если включена [буферизация](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-buffering) ответов SCGI-сервера, и ответ не вмещается целиком в буферы, заданные директивами [scgi_buffer_size](#adc-scgi-buffer-size) и [scgi_buffers](#adc-scgi-buffers), часть ответа может быть записана во временный файл. Эта директива задает максимальный размер временного файла. Размер данных, сбрасываемых во временный файл за один раз, задается директивой [scgi_temp_file_write_size](#adc-scgi-temp-file-write-size).
| `0` | отключает возможность буферизации ответов во временные файлы |
|-------|----------------------------------------------------------------|
#### NOTE
Данное ограничение не распространяется на ответы, которые будут [кэшированы](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-cache) или сохранены [на диске](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-store).
### scgi_next_upstream
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_next_upstream` `error` | `timeout` | `invalid_header` | `http_500` | `http_503` | `http_403` | `http_404` | `http_429` | `non_idempotent` | `off` ...; |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `scgi_next_upstream error timeout;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, в каких случаях запрос будет передан следующему серверу:
| `error` | произошла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `timeout` | произошел таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
| `invalid_header` | сервер вернул пустой или неверный ответ; |
| `http_500` | сервер вернул ответ с кодом 500; |
| `http_503` | сервер вернул ответ с кодом 503; |
| `http_403` | сервер вернул ответ с кодом 403; |
| `http_404` | сервер вернул ответ с кодом 404; |
| `http_429` | сервер вернул ответ с кодом 429; |
| `non_idempotent` | обычно запросы с [неидемпотентным](https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2) методом (POST, LOCK, PATCH) не передаются на другой сервер, если запрос серверу группы уже был отправлен; включение параметра явно разрешает повторять подобные запросы; |
| `off` | запрещает передачу запроса следующему серверу. |
#### NOTE
Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту еще ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа клиенту, то действие директивы на такой запрос не распространяется.
Директива также определяет, что считается [неудачной попыткой](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) работы с сервером.
| `error`
`timeout`
`invalid_header` | всегда считаются неудачными попытками, даже если они не указаны в директиве |
|--------------------------------------------------------|-------------------------------------------------------------------------------|
| `http_500`
`http_503`
`http_429` | считаются неудачными попытками, только если они указаны в директиве |
| `http_403`
`http_404` | никогда не считаются неудачными попытками |
Передача запроса следующему серверу может быть ограничена по [количеству попыток](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-next-upstream-tries) и по [времени](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-next-upstream-timeout).
### scgi_next_upstream_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_next_upstream_timeout` время; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `scgi_next_upstream_timeout 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает время, в течение которого возможна передача запроса [следующему](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### scgi_next_upstream_tries
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_next_upstream_tries` число; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `scgi_next_upstream_tries 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает число допустимых попыток для передачи запроса [следующему](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-next-upstream) серверу.
| `0` | отключает это ограничение |
|-------|-----------------------------|
### scgi_no_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_no_cache` строка ...; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает условия, при которых ответ не будет сохраняться в кэш. Если значение хотя бы одного из строковых параметров непустое и не равно "0", то ответ не будет сохранен:
```nginx
scgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
scgi_no_cache $http_pragma $http_authorization;
```
Можно использовать совместно с директивой [scgi_cache_bypass](#adc-scgi-cache-bypass).
### scgi_param
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_param` параметр значение [`if_not_empty`]; |
|------------------------------------------------------------------------------------------|----------------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает параметр, который будет передаваться SCGI-серверу. В качестве значения можно использовать текст, переменные и их комбинации. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы SCGI-param.
Стандартные [переменные окружения CGI](https://datatracker.ietf.org/doc/html/rfc3875#section-4.1) должны передаваться как заголовки SCGI, см. файл scgi_params из дистрибутива:
```nginx
location / {
include scgi_params;
# ...
}
```
В стандартном файле `scgi_params` параметр `REQUEST_METHOD`
задается как `$upstream_request_method`.
Если директива указана с `if_not_empty`, то такой параметр с пустым значением передаваться на сервер не будет:
```nginx
scgi_param HTTPS $https if_not_empty;
```
### scgi_pass
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_pass` uri; |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location, if в location |
Задает адрес SCGI-сервера. Адрес может быть указан в виде доменного имени или IP-адреса, и порта:
```nginx
scgi_pass localhost:9000;
```
или в виде пути UNIX-сокета:
```nginx
scgi_pass unix:/tmp/scgi.socket;
```
Если доменному имени соответствует несколько адресов, то все они будут использоваться по очереди (round-robin). Кроме того, в качестве адреса можно указать [группу серверов](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream).
В значении параметра можно использовать переменные. В этом случае, если адрес указан в виде доменного имени, имя ищется среди описанных групп серверов и если не найдено, то определяется с помощью [resolver](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-resolver)'а.
#### NOTE
Если `scgi_pass` стоит в `location` с косой чертой в конце префикса
(например, `location /name/`),
и при этом в директиве [auto_redirect](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-auto-redirect) указано `default`,
запросы без косой черты в конце будут перенаправляться (`/name -> /name/`).
### scgi_pass_header
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_pass_header` поле ...; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает передавать от SCGI-сервера клиенту [запрещенные для передачи](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-hide-header) поля заголовка.
### scgi_pass_request_body
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_pass_request_body` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `scgi_pass_request_body on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запретить передачу исходного тела запроса на SCGI-сервер. См. также директиву [scgi_pass_request_headers](#adc-scgi-pass-request-headers).
### scgi_pass_request_headers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_pass_request_headers` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | `scgi_pass_request_headers on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет запретить передачу полей заголовка исходного запроса на SCGI-сервер. См. также директиву [scgi_pass_request_body](#adc-scgi-pass-request-body).
### scgi_read_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_read_timeout` время; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `scgi_read_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при чтении ответа SCGI-сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени SCGI-сервер ничего не передаст, соединение закрывается.
### scgi_request_buffering
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_request_buffering` `on` | `off`; |
|------------------------------------------------------------------------------------------|------------------------------------------|
| По умолчанию | `scgi_request_buffering on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает или запрещает использовать буферизацию тела запроса клиента.
| `on` | тело запроса полностью [читается](https://angie.software//angie/docs/configuration/modules/http/index.md#client-body-buffer-size) от клиента перед отправкой запроса на SCGI-сервер. |
|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | тело запроса отправляется на SCGI-сервер сразу же по мере его поступления. В этом случае запрос не может быть передан [следующему серверу](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-next-upstream), если Angie уже начал отправку тела запроса. |
Если для отправки тела исходного запроса используется HTTP/1.1 и передача данных частями (chunked transfer encoding), то тело запроса буферизуется независимо от значения директивы.
### scgi_send_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_send_timeout` время; |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию | `scgi_send_timeout 60s;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает таймаут при передаче запроса SCGI-серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени SCGI-сервер не примет новых данных, соединение закрывается.
### scgi_socket_keepalive
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_socket_keepalive` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию | `scgi_socket_keepalive off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Конфигурирует поведение "TCP keepalive" для исходящих соединений к SCGI-серверу.
| `""` | По умолчанию для сокета действуют настройки операционной системы. |
|--------|---------------------------------------------------------------------|
| `on` | для сокета включается параметр SO_KEEPALIVE |
### scgi_store
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_store` `on` | `off` | строка; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `scgi_store off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает сохранение на диск файлов.
| `on` | сохраняет файлы в соответствии с путями, указанными в директивах [alias](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-alias) или [root](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-root) |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `off` | запрещает сохранение файлов |
Имя файла можно задать явно с помощью `строки` с переменными:
```nginx
scgi_store /data/www$original_uri;
```
Время изменения файлов выставляется согласно полученному полю `Last-Modified` в заголовке ответа. Ответ сначала записывается во временный файл, а потом этот файл переименовывается. Временный файл и постоянное место хранения ответа могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешевой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой системе, что и каталог с временными файлами, задаваемый директивой [scgi_temp_path](#adc-scgi-temp-path) для данного location.
Директиву можно использовать для создания локальных копий статических неизменяемых файлов:
```nginx
location /images/ {
root /data/www;
error_page 404 = /fetch$uri;
}
location /fetch/ {
internal;
scgi_pass backend:9000;
# ...
scgi_store on;
scgi_store_access user:rw group:rw all:r;
scgi_temp_path /data/temp;
alias /data/www/;
}
```
### scgi_store_access
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_store_access` пользователи:права ...; |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| По умолчанию | `scgi_store_access user:rw;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает права доступа для создаваемых файлов и каталогов, например,
```nginx
scgi_store_access user:rw group:rw all:r;
```
Если заданы какие-либо права для group или all, то права для user указывать необязательно:
```nginx
scgi_store_access group:rw all:r;
```
### scgi_temp_file_write_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_temp_file_write_size` размер; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `scgi_temp_file_write_size 8k|16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Ограничивает размер данных, сбрасываемых во временный файл за один раз, при включенной буферизации ответов SCGI-сервера во временные файлы. По умолчанию размер ограничен двумя буферами, заданными директивами [scgi_buffer_size](#adc-scgi-buffer-size) и [scgi_buffers](#adc-scgi-buffers). Максимальный размер временного файла задается директивой [scgi_max_temp_file_size](#adc-scgi-max-temp-file-size).
### scgi_temp_path
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `scgi_temp_path` путь [уровень1 [уровень2 [уровень3]]]\`; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию | `scgi_temp_path scgi_temp;`
(путь зависит от [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-scgi-temp-path`) |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает имя каталога для хранения временных файлов с данными, полученными от SCGI-серверов. В каталоге может использоваться иерархия подкаталогов до трех уровней. Например, при такой конфигурации
```nginx
scgi_temp_path /spool/angie/scgi_temp 1 2;
```
временный файл будет следующего вида:
```nginx
/spool/angie/scgi_temp/7/45/00000123457
```
См. также параметр `use_temp_path` директивы [scgi_cache_path](#adc-scgi-cache-path).
# https://angie.software/adc/docs/load_balancer/reference/http/http_secure_link.md
# Secure Link
Позволяет проверять аутентичность запрашиваемых ссылок, защищать ресурсы от несанкционированного доступа, а также ограничивать срок действия ссылок.
Правильность запрашиваемой ссылки проверяется сравнением переданного в запросе значения контрольной суммы со значением, вычисляемым для запроса. Если ссылка имеет ограниченный срок действия и он истек, ссылка считается устаревшей. Результат этих проверок делается доступным в переменной [$secure_link](#adc-v-secure-link).
Модуль реализует два альтернативных режима работы. В первом режиме, который включается директивой [secure_link_secret](#adc-secure-link-secret), можно проверить аутентичность запрашиваемых ссылок и защитить их от несанкционированного доступа. Второй режим включается директивами [secure_link](#adc-secure-link) и [secure_link_md5](#adc-secure-link-md5), и позволяет также ограничить срок действия ссылок.
## Директивы
### secure_link
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `secure_link` выражение; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает строку с переменными, из которой будет выделено значение контрольной суммы и время действия ссылки.
Используемые в выражении переменные обычно связаны с запросом; см. [пример](https://angie.software//angie/docs/configuration/modules/http/http_secure_link.md#secure-link-md5) ниже.
Выделенное из строки значение контрольной суммы сравнивается со значением MD5-хэша, вычисляемым для выражения, заданного директивой [secure_link_md5](#adc-secure-link-md5).
Если контрольные суммы не совпадают, значением переменной [$secure_link](#adc-v-secure-link) становится пустая строка. Если контрольные суммы совпадают, проверяется время действия ссылки.
Если срок действия ссылки задан и истек, переменная [$secure_link](#adc-v-secure-link) получает значение `0`. В противном случае она получает значение `1`. Значение MD5-хэша передается в запросе закодированным в base64url.
Если ссылка имеет ограниченный срок действия, время ее действия задается в секундах с начала эпохи (1 января 1970 года 00:00:00 GMT). Значение указывается в выражении после MD5-хэша и отделяется от него запятой. Время действия ссылки, переданное в запросе, делается доступным в переменной [$secure_link_expires](#adc-v-secure-link-expires) для использования в директиве [secure_link_md5](#adc-secure-link-md5). Если время действия ссылки не задано, ссылка имеет неограниченный срок действия.
### secure_link_md5
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `secure_link_md5` выражение; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает выражение, для которого считается значение MD5-хэша, сравниваемое с переданным в запросе.
Выражение должно содержать защищаемую часть ссылки (ресурс) и секретную составляющую. Если ссылка имеет ограниченный срок действия, выражение также должно содержать [$secure_link_expires](#adc-v-secure-link-expires).
Для предотвращения несанкционированного доступа выражение может содержать информацию о клиенте, например, его адрес и версию браузера.
Пример:
```nginx
location /s/ {
secure_link $arg_md5,$arg_expires;
secure_link_md5 "$secure_link_expires$uri$remote_addr secret";
if ($secure_link = "") {
return 403;
}
if ($secure_link = "0") {
return 410;
}
# ...
}
```
Ссылка "/s/link?md5=_e4Nc3iduzkWRm01TBBNYw&expires=2147483647" ограничивает доступ к "/s/link" для клиента с IP-адресом 127.0.0.1. Ссылка также имеет ограниченный срок действия до 19 января 2038 года (GMT).
Значение аргумента запроса md5 на UNIX можно получить так:
```console
echo -n '2147483647/s/link127.0.0.1 secret' | \
openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =
```
### secure_link_secret
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `secure_link_secret` слово; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location |
Задает секретное слово для проверки аутентичности запрашиваемых ссылок.
Полный URI запрашиваемой ссылки выглядит так:
```console
/префикс/хэш/ссылка
```
где хэш — MD5-хэш в шестнадцатеричном виде, вычисленный для конкатенации ссылки и секретного слова, а префикс — произвольная строка без косых черт.
Если запрашиваемая ссылка проходит проверку на аутентичность, значением переменной [$secure_link](#adc-v-secure-link) становится ссылка, выделенная из URI запроса. В противном случае значением переменной [$secure_link](#adc-v-secure-link) становится пустая строка.
Пример:
```nginx
location /p/ {
secure_link_secret secret;
if ($secure_link = "") {
return 403;
}
rewrite ^ /secure/$secure_link;
}
location /secure/ {
internal;
}
```
По запросу "/p/5e814704a28d9bc1914ff19fa0c4a00a/link" будет выполнено внутреннее перенаправление на "/secure/link".
Значение хэша для данного примера на UNIX можно получить так:
```console
echo -n 'linksecret' | openssl md5 -hex
```
## Встроенные переменные
### `$secure_link`
Результат проверки ссылки. Конкретное значение зависит от выбранного режима работы.
### `$secure_link_expires`
Время действия ссылки, переданное в запросе. Предназначено исключительно для использования в директиве [secure_link_md5](#adc-secure-link-md5).
# https://angie.software/adc/docs/load_balancer/reference/http/http_slice.md
# Slice
Фильтр, который разбивает запрос на подзапросы, каждый из которых возвращает определенный диапазон ответа. Фильтр обеспечивает более эффективное кэширование больших ответов.
## Пример конфигурации
```nginx
location / {
slice 1m;
proxy_cache cache;
proxy_cache_key $uri$is_args$args$slice_range;
proxy_set_header Range $slice_range;
proxy_cache_valid 200 206 1h;
proxy_pass http://localhost:8000;
}
```
В данном примере ответ разбивается на кэшируемые фрагменты размером в 1 мегабайт.
## Директивы
### slice
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `slice` размер; |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию | `slice 0;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает размер фрагмента. Нулевое значение запрещает разбиение ответов на фрагменты.
#### WARNING
Обратите внимание, что слишком низкое значение может привести к излишнему потреблению памяти и открытию большого количества файлов.
Для того, чтобы подзапрос вернул необходимый диапазон, переменная [$slice_range](#adc-v-slice-range) должна быть передана на проксируемый сервер в качестве поля `Range` заголовка запроса. Если включено [кэширование](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache), то необходимо добавить [$slice_range](#adc-v-slice-range) в [ключ кэширования](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-key) и [включить](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-valid) кэширование ответов с кодом 206.
## Встроенные переменные
### `$slice_range`
текущий диапазон фрагмента в формате [HTTP byte range](https://datatracker.ietf.org/doc/html/rfc7233#section-2.1), например bytes=0-1048575.
# https://angie.software/adc/docs/load_balancer/reference/http/http_split_clients.md
# Split Clients
Модуль генерирует переменные для A/B-тестирования, канареечных релизов
и других сценариев, которые направляют определенный процент клиентов на один
сервер или конфигурацию, а остальных — куда-то еще.
## Пример конфигурации
```nginx
http {
split_clients "${remote_addr}AAA" $variant {
0.5% .one;
2.0% .two;
* "";
}
server {
location / {
index index${variant}.html;
```
## Директивы
### split_clients
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `split_clients` строка $переменная { ... } |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http |
Создает $переменную, хэшируя строку;
переменные в строке подставляются,
результат хэшируется,
затем по значению хэша выбирается строковое значение $переменной.
Функция хэширования использует
[MurmurHash2](https://en.wikipedia.org/wiki/MurmurHash#MurmurHash2)
(32 бит),
и весь диапазон ее значений
(с 0 по 4294967295)
сопоставляется с корзинами в порядке появления;
процентные величины определяют размер корзин.
В конце может стоять метасимвол (`*`);
хэши, не попавшие в другие корзины, сопоставляются с приданным ему значением.
Пример:
```nginx
split_clients "${remote_addr}AAA" $variant {
0.5% .one;
2.0% .two;
* "";
}
```
Здесь после подстановки в строке `$*remote_addr*AAA`
значения хэша распределяются следующим образом:
- значения от 0 до 21474835 (0,5%) дают `.one`;
- значения от 21474836 до 107374180 (2%) дают `.two`;
- значения от 107374181 до 4294967295 (все остальные) дают `""`
(пустую строку).
# https://angie.software/adc/docs/load_balancer/reference/http/http_ssi.md
# SSI
Фильтр, обрабатывающий команды SSI (Server Side Includes) в проходящих через него ответах.
## Пример конфигурации
```nginx
location / {
ssi on;
# ...
}
```
## Директивы
### ssi
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssi` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `ssi off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if в location |
Разрешает или запрещает обработку команд SSI в ответах.
### ssi_last_modified
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssi_last_modified` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `ssi_last_modified off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет сохранить поле заголовка `Last-Modified` исходного ответа во время обработки SSI для лучшего кэширования ответов.
По умолчанию поле заголовка удаляется, так как содержимое ответа изменяется во время обработки и может содержать динамически созданные элементы или части, которые изменились независимо от исходного ответа.
### ssi_min_file_chunk
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssi_min_file_chunk` размер; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `ssi_min_file_chunk 1k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает минимальный размер частей ответа, хранящихся на диске, начиная с которого имеет смысл посылать их с помощью [sendfile](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-sendfile).
### ssi_silent_errors
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssi_silent_errors` `on` | `off`; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `ssi_silent_errors off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает не выводить строку "[an error occurred while processing the directive]", если во время обработки SSI произошла ошибка.
### ssi_types
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssi_types` mime-тип ...; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `ssi_types text/html;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает обработку команд SSI в ответах с указанными MIME-типами в дополнение к `text/html`. Специальное значение "\*" соответствует любому MIME-типу.
### ssi_value_length
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssi_value_length` длина; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `ssi_value_length 256;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает максимальную длину значений параметров в SSI-командах.
## Команды SSI
Общий формат команд SSI такой:
```html
```
Поддерживаются следующие команды:
### `block`
Описывает блок, который можно использовать как заглушку в команде include. Внутри блока могут быть другие команды SSI. Параметр команды:
#### `name`
имя блока.
Пример:
```html
заглушка
```
### `config`
Задает некоторые параметры, используемые при обработке SSI, а именно:
#### `errmsg`
строка, выводящаяся при ошибке во время обработки SSI. По умолчанию выводится такая строка:
```none
`[an error occurred while processing the directive]`
```
#### `timefmt`
строка формата, передаваемая функции `strftime()` для вывода даты и времени. По умолчанию используется такой формат:
```none
`"%A, %d-%b-%Y %H:%M:%S %Z"`
```
Для вывода времени в секундах подходит формат "%s".
### `echo`
Выводит значение переменной. Параметры команды:
#### `var`
имя переменной.
#### `encoding`
способ кодирования. Возможны три значения — `none`, `url` и `entity`. По умолчанию используется `entity`.
#### `default`
нестандартный параметр, задающий строку, которая выводится, если переменная не определена. По умолчанию выводится строка `(none)`.
Команда
```html
```
заменяет такую последовательность команд:
```html
нет
```
### `if`
Выполняет условное включение. Поддерживаются следующие команды:
```html
...
...
...
```
На данный момент поддерживается только один уровень вложенности. Параметр команды:
#### `expr`
выражение. В выражении может быть:
* проверка существования переменной:
```html
```
* сравнение переменной с текстом:
```html
```
* сравнение переменной с регулярным выражением:
```html
```
Если в text встречаются переменные, то производится подстановка их значений. В регулярном выражении можно задать позиционные и именованные группы захвата, а затем использовать их через переменные, например:
```html
```
### `include`
Включает в ответ результат другого запроса. Параметры команды:
#### `file`
задает включаемый файл, например:
```html
```
#### `virtual`
задает включаемый запрос, например:
```html
```
Несколько запросов, указанных на одной странице и обрабатываемых проксируемыми или FastCGI/uwsgi/SCGI/gRPC-серверами, работают параллельно. Если нужна последовательная обработка, следует воспользоваться параметром wait.
#### `stub`
нестандартный параметр, задающий имя блока, содержимое которого будет выведено, если тело ответа на включаемый запрос пустое или если при исполнении запроса произошла ошибка, например:
```html
```
Содержимое замещающего блока обрабатывается в контексте включаемого запроса.
#### `wait`
нестандартный параметр, указывающий, нужно ли ждать полного исполнения данного запроса, прежде чем продолжать выполнение SSI, например:
```html
```
#### `set`
нестандартный параметр, указывающий, что удачный результат выполнения запроса нужно записать в заданную переменную, например:
```html
```
Максимальный размер ответа задается директивой [subrequest_output_buffer_size](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-subrequest-output-buffer-size):
```nginx
location /remote/ {
subrequest_output_buffer_size 64k;
# ...
}
```
### `set`
Присваивает значение переменной. Параметры команды:
#### `var`
имя переменной.
#### `value`
значение переменной. Если в присваиваемом значении есть переменные, то производится подстановка их значений.
## Встроенные переменные
### `$date_local`
текущее время в локальной временной зоне. Формат задается командой config с параметром timefmt.
### `$date_gmt`
текущее время в GMT. Формат задается командой config с параметром timefmt.
# https://angie.software/adc/docs/load_balancer/reference/http/http_ssl.md
# SSL
Обеспечивает работу по протоколу HTTPS.
#### NOTE
Для этого модуля нужна библиотека OpenSSL.
## Пример конфигурации
Для уменьшения загрузки процессора рекомендуется
* установить число [рабочих процессов](https://angie.software//angie/docs/configuration/modules/core.md#worker-processes) равным числу процессоров,
* разрешить [keep-alive](https://angie.software//angie/docs/configuration/modules/http/index.md#keepalive-timeout) соединения,
* включить [разделяемый кэш](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-session-cache) сессий,
* выключить [встроенный кэш](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-session-cache) сессий
* и, возможно, увеличить [время жизни](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-session-timeout) сессии (по умолчанию 5 минут):
```nginx
worker_processes auto;
http {
# ...
server {
listen 443 ssl;
keepalive_timeout 70;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
ssl_certificate /usr/local/angie/conf/cert.pem;
ssl_certificate_key /usr/local/angie/conf/cert.key;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
# ...
}
```
## Директивы
### ssl_buffer_size
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_buffer_size` размер; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `ssl_buffer_size 16k;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает размер буфера, используемого при отправке данных.
По умолчанию размер буфера равен 16k, что соответствует минимальным накладным расходам при передаче больших ответов. С целью минимизации времени получения начала ответа (Time To First Byte) может быть полезно использовать меньшие значения, например:
```nginx
ssl_buffer_size 4k;
```
### ssl_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_certificate` файл; |
|------------------------------------------------------------------------------------------|---------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Указывает файл с сертификатом в формате PEM для данного виртуального сервера. Если вместе с основным сертификатом нужно указать промежуточные, то они должны находиться в этом же файле в следующем порядке: сначала основной сертификат, а затем промежуточные. В этом же файле может находиться секретный ключ в формате PEM.
Эта директива может быть указана несколько раз для загрузки сертификатов разных типов, например RSA и ECDSA:
```nginx
server {
listen 443 ssl;
server_name example.com;
ssl_certificate example.com.rsa.crt;
ssl_certificate_key example.com.rsa.key;
ssl_certificate example.com.ecdsa.crt;
ssl_certificate_key example.com.ecdsa.key;
# ...
}
```
Возможность задавать отдельные цепочки сертификатов для разных сертификатов есть только в OpenSSL 1.0.2 и выше. Для более старых версий следует указывать только одну цепочку сертификатов.
#### NOTE
В имени файла можно использовать переменные при использовании OpenSSL 1.0.2 и выше:
```nginx
ssl_certificate $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;
```
При использовании переменных сертификат загружается при каждой операции SSL-рукопожатия, что может отрицательно влиять на производительность.
Вместо файла можно указать значение `data:$переменная`, при котором
сертификат загружается из переменной без использования промежуточных файлов.
Ненадлежащее использование подобного синтаксиса может быть небезопасно, например данные секретного ключа могут попасть в [лог ошибок](https://angie.software//angie/docs/configuration/modules/core.md#error-log).
#### NOTE
> Нужно иметь в виду, что из-за ограничения протокола HTTPS для максимальной совместимости виртуальные серверы должны слушать на [разных IP-адресах](https://angie.software//angie/docs/configuration/ssl.md#https-separate-ips).
Если задан режим [ssl_ntls](#adc-ssl-ntls), директива может принимать два аргумента
(части ключа для подписи и шифрования)
вместо одного:
```nginx
listen ... ssl;
ssl_ntls on;
# двойной сертификат NTLS
ssl_certificate sign.crt enc.crt;
ssl_certificate_key sign.key enc.key;
# можно использовать наряду с обычным сертификатом RSA
ssl_certificate rsa.crt;
ssl_certificate rsa.key;
```
### ssl_certificate_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_certificate_cache` `off`;
`ssl_certificate_cache` `max=`N [`inactive=`time] [`valid=`time]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
| Значение по умолчанию | `ssl_certificate_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Определяет кэш для хранения [SSL-сертификатов](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate) и [секретных ключей](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate-key), заданных через переменные.
Директива поддерживает следующие параметры:
- `max` — устанавливает максимальное количество элементов в кэше. При
переполнении кэша удаляются наименее недавно использованные (LRU) элементы.
- `inactive` — определяет время, после которого элемент будет удален, если
к нему не было обращений. Значение по умолчанию — 10 секунд.
- `valid` — определяет время, в течение которого элемент кэша считается
действительным и может использоваться повторно. Значение по умолчанию — 60
секунд. По истечении этого времени сертификаты перезагружаются или проходят
повторную проверку.
- `off` — отключает кэш.
Пример:
```nginx
ssl_certificate $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;
ssl_certificate_cache max=1000 inactive=20s valid=1m;
```
### ssl_certificate_compression
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_certificate_compression` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------------------|
| Значение по умолчанию | `ssl_certificate_compression off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает сжатие TLS 1.3 [сертификатов сервера](https://datatracker.ietf.org/doc/html/rfc8879).
#### NOTE
Директива поддерживается при использовании OpenSSL версии 3.2 и выше; список поддерживаемых алгоритмов сжатия предоставляется библиотекой.
#### NOTE
Директива поддерживается при использовании [BoringSSL](https://boringssl.googlesource.com/boringssl/); список поддерживаемых алгоритмов сжатия включает `zlib`.
Если включен [ssl_stapling](#adc-ssl-stapling), сжатие сертификатов отключается.
### ssl_certificate_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_certificate_key` файл; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Указывает файл с секретным ключом в формате PEM для данного виртуального сервера.
#### NOTE
В имени файла можно использовать переменные при использовании OpenSSL 1.0.2 и выше.
Вместо `файла` можно указать значение `engine:имя:id`, которое загружает
ключ с указанным id из движка OpenSSL с заданным именем.
Вместо `файла` можно указать значение `store:scheme:id`, которое
используется для загрузки ключа с указанным id и URI-схемой scheme,
зарегистрированной в OpenSSL provider, например [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512).
Вместо `файла` также можно указать значение `data:$переменная`, при
котором секретный ключ загружается из переменной без использования промежуточных
файлов. При этом следует учитывать, что ненадлежащее использование подобного
синтаксиса может быть небезопасно, например данные секретного ключа могут
попасть в [лог ошибок](https://angie.software//angie/docs/configuration/modules/core.md#error-log).
> Если задан режим [ssl_ntls](#adc-ssl-ntls), директива может принимать два аргумента
> (части ключа для подписи и шифрования)
> вместо одного:
> ```nginx
> listen ... ssl;
> ssl_ntls on;
> # двойной сертификат NTLS
> ssl_certificate sign.crt enc.crt;
> ssl_certificate_key sign.key enc.key;
> # можно использовать наряду с обычным сертификатом RSA
> ssl_certificate rsa.crt;
> ssl_certificate rsa.key;
> ```
### ssl_ciphers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ciphers` шифры; |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию | `ssl_ciphers HIGH:!aNULL:!MD5;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Описывает разрешенные шифры. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL, например:
```nginx
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
```
Список шифров зависит от установленной версии OpenSSL.
Полный список можно посмотреть с помощью команды `openssl ciphers`.
#### WARNING
Директива `ssl_ciphers` *не* настраивает шифры для TLS 1.3 при
использовании OpenSSL. Для настройки шифров TLS 1.3 в OpenSSL используйте
директиву [ssl_conf_command](#adc-ssl-conf-command), добавленную для расширенной
конфигурации SSL.
- В LibreSSL шифры TLS 1.3 *можно* настраивать с помощью
`ssl_ciphers`.
- В BoringSSL шифры TLS 1.3 настроить невозможно.
### ssl_client_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_client_certificate` файл; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Указывает файл с доверенными сертификатами CA в формате PEM, которые используются для [проверки](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-verify-client) клиентских сертификатов и ответов OCSP, если включен [ssl_stapling](#adc-ssl-stapling).
Список сертификатов будет отправляться клиентам. Если это нежелательно, можно воспользоваться директивой [ssl_trusted_certificate](#adc-ssl-trusted-certificate).
### ssl_conf_command
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_conf_command` имя значение; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает произвольные [конфигурационные команды](https://docs.openssl.org/master/man3/SSL_CONF_cmd/) OpenSSL.
#### NOTE
Директива поддерживается при использовании OpenSSL 1.0.2 и выше.
Чтобы настроить шифры TLS 1.3 в OpenSSL, используйте команду `ciphersuites`.
На одном уровне может быть указано несколько директив ssl_conf_command:
```nginx
ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;
```
Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы ssl_conf_command.
#### WARNING
Изменение настроек OpenSSL напрямую может привести к неожиданному поведению.
### ssl_crl
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_crl` файл; |
|------------------------------------------------------------------------------------------|-------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Указывает файл с отозванными сертификатами (CRL) в формате PEM, используемыми для [проверки](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-verify-client) клиентских сертификатов.
### ssl_dhparam
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_dhparam` файл; |
|------------------------------------------------------------------------------------------|-----------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Указывает файл с параметрами для DHE-шифров.
#### WARNING
По умолчанию параметры не заданы, и соответственно DHE-шифры не будут использоваться.
### ssl_early_data
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_early_data` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | `ssl_early_data off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает или запрещает TLS 1.3 [early data](https://datatracker.ietf.org/doc/html/rfc8446#section-2.3).
Запросы, отправленные внутри early data, могут быть подвержены [атакам повторного воспроизведения](https://datatracker.ietf.org/doc/html/rfc8470) (replay). Для защиты от подобных атак на уровне приложения необходимо использовать переменную [$ssl_early_data](#adc-v-ssl-early-data).
```nginx
proxy_set_header Early-Data $ssl_early_data;
```
#### NOTE
Директива поддерживается при использовании OpenSSL 1.1.1 и выше или [BoringSSL](https://boringssl.googlesource.com/boringssl/).
### ssl_encrypted_hello_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_encrypted_hello_key` файл; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Указывает файл с приватным ключом ECH и списком ECHConfigList в формате PEM.
Директива может быть указана несколько раз.
Требуется сборка OpenSSL или BoringSSL с поддержкой Encrypted Client Hello (ECH),
иначе директива не поддерживается.
### ssl_ecdh_curve
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ecdh_curve` кривая; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `ssl_ecdh_curve auto;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает кривую для ECDHE-шифров.
#### NOTE
При использовании OpenSSL 1.0.2 и выше можно указывать несколько кривых, например:
```nginx
ssl_ecdh_curve prime256v1:secp384r1;
```
Специальное значение `auto` соответствует встроенному в библиотеку OpenSSL списку кривых для OpenSSL 1.0.2 и выше, или prime256v1 для более старых версий.
#### NOTE
При использовании OpenSSL 1.0.2 и выше директива задает список кривых, поддерживаемых сервером. Поэтому для работы ECDSA-сертификатов важно, чтобы список включал кривые, используемые в сертификатах.
### ssl_ntls
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ntls` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию | `ssl_ntls off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Включает серверную поддержку NTLS при использовании TLS библиотеки [TongSuo](https://github.com/Tongsuo-Project/Tongsuo)
```nginx
listen ... ssl;
ssl_ntls on;
```
#### NOTE
Angie необходимо собрать с использованием параметра конфигурации `--with-ntls`, с соответствующей SSL библиотекой с поддержкой NTLS
```default
./configure --with-openssl=../Tongsuo-8.3.0 \
--with-openssl-opt=enable-ntls \
--with-ntls
```
### ssl_ocsp
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ocsp` `on` | `off` | `leaf`; |
|------------------------------------------------------------------------------------------|-------------------------------------|
| По умолчанию | `ssl_ocsp off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Включает проверку OCSP для цепочки клиентских сертификатов. Параметр `leaf` включает проверку только клиентского сертификата.
Для работы проверки OCSP необходимо дополнительно установить значение директивы [ssl_verify_client](#adc-ssl-verify-client) в `on` или `optional`.
Для преобразования имени хоста OCSP-респондера в адрес необходимо дополнительно задать директиву [resolver](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-resolver).
Пример:
```nginx
ssl_verify_client on;
ssl_ocsp on;
resolver 127.0.0.53;
```
### ssl_ocsp_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ocsp_cache` `off` | [shared:имя:размер]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| По умолчанию | `ssl_ocsp_cache off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает имя и размер кэша, который хранит статус клиентских сертификатов для проверки OCSP-ответов. Кэш разделяется между всеми рабочими процессами. Кэш с одинаковым названием может использоваться в нескольких виртуальных серверах.
Параметр `off` запрещает использование кэша.
### ssl_ocsp_responder
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ocsp_responder` uri; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Переопределяет URI OCSP-респондера, указанный в расширении сертификата ["Authority Information Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1) для [проверки](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ocsp) клиентских сертификатов.
Поддерживаются только OCSP-респондеры на основе `http://`:
```nginx
ssl_ocsp_responder http://ocsp.example.com/;
```
### ssl_password_file
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_password_file` файл; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает файл с паролями от [секретных ключей](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate-key), где каждый пароль указан на отдельной строке. Пароли применяются по очереди в момент загрузки ключа.
Пример:
```nginx
http {
ssl_password_file /etc/keys/global.pass;
...
server {
server_name www1.example.com;
ssl_certificate_key /etc/keys/first.key;
}
server {
server_name www2.example.com;
# вместо файла можно указать именованный канал
ssl_password_file /etc/keys/fifo;
ssl_certificate_key /etc/keys/second.key;
}
}
```
### ssl_prefer_server_ciphers
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_prefer_server_ciphers` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| По умолчанию | `ssl_prefer_server_ciphers off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
При использовании протоколов SSLv3 и TLS устанавливает приоритет серверных шифров над клиентскими.
### ssl_protocols
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`]; |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| По умолчанию | `ssl_protocols TLSv1.2 TLSv1.3;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает указанные протоколы.
#### NOTE
Параметры TLSv1.1 и TLSv1.2 работают только при использовании OpenSSL 1.0.1 и выше.
Параметр TLSv1.3 работает только при использовании OpenSSL 1.1.1 и выше.
### ssl_reject_handshake
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_reject_handshake` `on` | `off`; |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию | `ssl_reject_handshake off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Если включено, то операции SSL-рукопожатия в блоке [server](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-server) будут отклонены.
Например, в этой конфигурации отклоняются все операции SSL-рукопожатия с именем сервера, отличным от example.com:
```nginx
server {
listen 443 ssl default_server;
ssl_reject_handshake on;
}
server {
listen 443 ssl;
server_name example.com;
ssl_certificate example.com.crt;
ssl_certificate_key example.com.key;
}
```
### ssl_session_cache
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_cache` `off` | `none` | [builtin[:размер]] [shared:название:размер]; |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| По умолчанию | `ssl_session_cache none;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает тип и размеры кэшей для хранения параметров сессий. Тип кэша может быть следующим:
| `off` | жесткое запрещение использования кэша сессий: Angie явно сообщает клиенту, что сессии не могут использоваться повторно. |
|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `none` | мягкое запрещение использования кэша сессий: Angie сообщает клиенту, что сессии могут использоваться повторно, но на самом деле не хранит параметры сессии в кэше. |
| `builtin` | встроенный в OpenSSL кэш, используется в рамках только одного рабочего процесса. Размер кэша задается в сессиях. Если размер не задан, то он равен 20480 сессиям. Использование встроенного кэша может вести к фрагментации памяти. |
| `shared` | кэш, разделяемый между всеми рабочими процессами. Размер кэша задается в байтах, в 1 мегабайт может поместиться около 4000 сессий. У каждого разделяемого кэша должно быть произвольное название. Кэш с одинаковым названием может использоваться в нескольких виртуальных серверах. Также он используется для автоматического создания, хранения и периодического обновления ключей сессионных билетов TLS, если они не указаны явно с помощью директивы [ssl_session_ticket_key](#adc-ssl-session-ticket-key). |
Можно использовать одновременно оба типа кэша, например:
```nginx
ssl_session_cache builtin:1000 shared:SSL:10m;
```
однако использование только разделяемого кэша без встроенного должно быть более эффективным.
### ssl_session_ticket_key
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_ticket_key` файл; |
|------------------------------------------------------------------------------------------|----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает файл с секретным ключом, применяемым при шифровании и расшифровке сессионных билетов TLS. Директива необходима, если один и тот же ключ нужно использовать на нескольких серверах. По умолчанию используется случайно сгенерированный ключ.
Если указано несколько ключей, то только первый ключ используется для шифрования сессионных билетов TLS. Это позволяет настроить ротацию ключей, например:
```nginx
ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;
```
Файл должен содержать 80 или 48 байт случайных данных и может быть создан следующей командой:
```console
openssl rand 80 > ticket.key
```
В зависимости от размера файла для шифрования будет использоваться либо AES256 (для 80-байтных ключей), либо AES128 (для 48-байтных ключей).
### ssl_session_tickets
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_tickets` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `ssl_session_tickets on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает или запрещает возобновление сессий при помощи [сессионных билетов TLS](https://datatracker.ietf.org/doc/html/rfc5077).
### ssl_session_timeout
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_timeout` время; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `ssl_session_timeout 5m;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает время, в течение которого клиент может повторно использовать параметры сессии.
### ssl_stapling
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_stapling` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------|
| По умолчанию | `ssl_stapling off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает или запрещает [прикрепление OCSP-ответов](https://datatracker.ietf.org/doc/html/rfc6066#section-8) сервером. Пример:
```nginx
ssl_stapling on;
resolver 127.0.0.53;
```
Для работы OCSP-прикрепления должен быть известен сертификат издателя
сертификата сервера. Если в заданном директивой [ssl_certificate](#adc-ssl-certificate) файле не
содержится промежуточных сертификатов, то сертификат издателя сертификата
сервера следует поместить в файл, заданный директивой
[ssl_trusted_certificate](#adc-ssl-trusted-certificate).
#### WARNING
Для преобразования имени хоста OCSP-респондера в адрес необходимо
дополнительно задать директиву [resolver](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-resolver).
### ssl_stapling_file
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_stapling_file` файл; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Если значение задано, то вместо опроса OCSP-респондера, указанного в сертификате
сервера, ответ берется из указанного файла.
Ответ должен быть в формате DER и может быть сгенерирован командой
`openssl ocsp`.
### ssl_stapling_responder
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_stapling_responder` `uri`; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Переопределяет URI OCSP-респондера, указанный в расширении сертификата
["Authority Information Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1).
Поддерживаются только OCSP-респондеры на основе `http://`:
```nginx
ssl_stapling_responder http://ocsp.example.com/;
```
### ssl_stapling_verify
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_stapling_verify` `on` | `off`; |
|------------------------------------------------------------------------------------------|---------------------------------------|
| По умолчанию | `ssl_stapling_verify off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает или запрещает проверку ответов OCSP сервером.
Для работоспособности проверки сертификат издателя сертификата сервера, корневой
сертификат и все промежуточные сертификаты должны быть указаны как доверенные с
помощью директивы [ssl_trusted_certificate](#adc-ssl-trusted-certificate).
### ssl_trusted_certificate
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_trusted_certificate` файл; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Задает файл с доверенными сертификатами CA в формате PEM, которые используются
для [проверки](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-verify-client) клиентских сертификатов и ответов OCSP,
если включен [ssl_stapling](#adc-ssl-stapling).
В отличие от [ssl_client_certificate](#adc-ssl-client-certificate), список этих сертификатов не будет отправляться клиентам.
### ssl_verify_client
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_verify_client` `on` | `off` | `optional` | `optional_no_ca`; |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| По умолчанию | `ssl_verify_client off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Разрешает проверку клиентских сертификатов. Результат проверки доступен через переменную [$ssl_client_verify](#adc-v-ssl-client-verify).
| `optional` | запрашивает клиентский сертификат, и если сертификат был предоставлен, проверяет его |
|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `optional_no_ca` | запрашивает сертификат клиента, но не требует, чтобы он был подписан доверенным сертификатом CA. Это предназначено для случаев, когда фактическая проверка сертификата осуществляется внешним по отношению к Angie сервисом. |
### ssl_verify_depth
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_verify_depth` число; |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию | `ssl_verify_depth 1;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
Устанавливает глубину проверки в цепочке клиентских сертификатов.
## Обработка ошибок
Модуль `http_ssl` поддерживает несколько нестандартных кодов ошибок, которые можно использовать для перенаправления с помощью директивы [error_page](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-error-page):
| `495` | при проверке клиентского сертификата произошла ошибка; |
|---------|----------------------------------------------------------|
| `496` | клиент не предоставил требуемый сертификат; |
| `497` | обычный запрос был послан на порт HTTPS. |
Перенаправление делается после того, как запрос полностью разобран и доступны такие переменные, как [$request_uri](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-v-request-uri), [$uri](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-v-uri), [$args](https://angie.software//adc/docs/load_balancer/reference/http/http.md#adc-v-args) и другие переменные.
## Встроенные переменные
Модуль http_ssl поддерживает встроенные переменные:
### `$ssl_alpn_protocol`
возвращает протокол, выбранный при помощи ALPN во время SSL-рукопожатия, либо пустую строку.
### `$ssl_cipher`
возвращает название используемого шифра для установленного SSL-соединения.
### `$ssl_ciphers`
возвращает список шифров, поддерживаемых клиентом. Известные шифры указаны по имени, неизвестные указаны в шестнадцатеричном виде, например:
> AES128-SHA:AES256-SHA:0x00ff
#### NOTE
Переменная полностью поддерживается при использовании OpenSSL версии 1.0.2 и выше. При использовании более старых версий переменная доступна только для новых сессий и может содержать только известные шифры.
### `$ssl_client_escaped_cert`
возвращает клиентский сертификат в формате PEM (закодирован в формате urlencode) для установленного SSL-соединения.
### `$ssl_client_fingerprint`
возвращает SHA1-отпечаток клиентского сертификата для установленного SSL-соединения.
### `$ssl_client_i_dn`
возвращает строку "issuer DN" клиентского сертификата для установленного SSL-соединения согласно [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253).
### `$ssl_client_i_dn_legacy`
возвращает строку "issuer DN" клиентского сертификата для установленного SSL-соединения.
### `$ssl_client_raw_cert`
возвращает клиентский сертификат для установленного SSL-соединения в формате PEM.
### `$ssl_client_s_dn`
возвращает строку "subject DN" клиентского сертификата для установленного SSL-соединения согласно [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253).
### `$ssl_client_s_dn_legacy`
возвращает строку "subject DN" клиентского сертификата для установленного SSL-соединения.
### `$ssl_client_serial`
возвращает серийный номер клиентского сертификата для установленного SSL-соединения.
### `$ssl_client_sigalg`
возвращает [алгоритм подписи](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) для сертификата клиента в установленном SSL-соединении.
#### NOTE
Переменная поддерживается только при использовании OpenSSL версии 3.5 и выше. При использовании более старых версий значением переменной будет пустая строка.
#### NOTE
Переменная доступна только для новых сессий.
### `$ssl_client_v_end`
возвращает дату окончания срока действия клиентского сертификата.
### `$ssl_client_v_remain`
возвращает число дней, оставшихся до истечения срока действия клиентского сертификата.
### `$ssl_client_v_start`
возвращает дату начала срока действия клиентского сертификата.
### `$ssl_client_verify`
возвращает результат проверки клиентского сертификата: `SUCCESS`, `FAILED:reason` и, если сертификат не был предоставлен, `NONE`.
### `$ssl_curve`
возвращает согласованную кривую, использованную для обмена ключами во время SSL-рукопожатия. Известные кривые указаны по имени, неизвестные указаны в шестнадцатеричном виде, например:
> prime256v1
#### NOTE
Переменная поддерживается при использовании OpenSSL версии 3.0 и выше. При использовании более старых версий значением переменной будет пустая строка.
### `$ssl_curves`
возвращает список кривых, поддерживаемых клиентом. Известные кривые указаны по имени, неизвестные указаны в шестнадцатеричном виде, например:
> 0x001d:prime256v1:secp521r1:secp384r1
#### NOTE
Переменная поддерживается при использовании OpenSSL версии 1.0.2 и выше. При использовании более старых версий значением переменной будет пустая строка.
Переменная доступна только для новых сессий.
### `$ssl_early_data`
возвращает `1`, если используется TLS 1.3 [early data](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-early-data) и операция SSL-рукопожатия не завершена, иначе "".
### `$ssl_encrypted_hello`
возвращает `1`, если используется Encrypted Client Hello (ECH), иначе "".
### `$ssl_protocol`
возвращает протокол установленного SSL-соединения.
### `$ssl_server_cert_type`
принимает значения `RSA`, `DSA`, `ECDSA`, `ED448`,
`ED25519`, `SM2`, `RSA-PSS` или `unknown` в зависимости
от типа сертификата и ключа сервера.
### `$ssl_server_name`
возвращает имя сервера, запрошенное через [SNI](http://en.wikipedia.org/wiki/Server_Name_Indication).
### `$ssl_session_id`
возвращает идентификатор сессии установленного SSL-соединения.
### `$ssl_session_reused`
возвращает `r`, если сессия была использована повторно, иначе ".".
### `$ssl_sigalg`
возвращает [алгоритм подписи](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16) для сертификата сервера в установленном SSL-соединении.
#### NOTE
Переменная поддерживается только при использовании OpenSSL версии 3.5 и выше. При использовании более старых версий значением переменной будет пустая строка.
#### NOTE
Переменная доступна только для новых сессий.
# https://angie.software/adc/docs/load_balancer/reference/http/http_stub_status.md
# Stub Status
Предоставляет доступ к базовой информации о состоянии сервера.
## Пример конфигурации
```nginx
location = /basic_status {
stub_status;
}
```
В данной конфигурации создается простая веб-страница с основной информацией о состоянии, которая может выглядеть следующим образом:
```console
Active connections: 291
server accepts handled requests
16630948 16630948 31070465
Reading: 6 Writing: 179 Waiting: 106
```
## Директивы
### stub_status
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `stub_status`; |
|------------------------------------------------------------------------------------------|------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server, location |
Информация о состоянии будет доступна из данного location.
## Данные
Доступна следующая информация:
### `Active connections`
Текущее число активных клиентских соединений, включая Waiting-соединения.
### `accepts`
Суммарное число принятых клиентских соединений.
### `handled`
Суммарное число обработанных соединений.
Обычно значение этого параметра совпадает с `accepts`, если не достигнуто какое-нибудь системное ограничение (например, лимит [worker_connections](https://angie.software//adc/docs/load_balancer/reference/core.md#adc-worker-connections)).
### `requests`
Суммарное число клиентских запросов.
### `Reading`
Текущее число соединений, в которых Angie в настоящий момент читает заголовок запроса.
### `Writing`
Текущее число соединений, в которых Angie в настоящий момент отвечает клиенту.
### `Waiting`
Текущее число бездействующих клиентских соединений в ожидании запроса.
## Встроенные переменные
### `$connections_active`
то же, что и значение Active connections;
### `$connections_reading`
то же, что и значение Reading;
### `$connections_writing`
то же, что и значение Writing;
### `$connections_waiting`
то же, что и значение Waiting.
# https://angie.software/adc/docs/load_balancer/reference/http/http_sub.md
# Sub
Фильтр, изменяющий в ответе одну заданную строку на другую.
## Пример конфигурации
```nginx
location / {
sub_filter '
## Директивы
### sub_filter
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `sub_filter` строка замена; |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Задает строку, которую нужно заменить, и строку замены. Заменяемая строка проверяется без учета регистра. В заменяемой строке и в строке замены можно использовать переменные. На одном уровне конфигурации может быть указано несколько директив `sub_filter`. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы `sub_filter`.
### sub_filter_last_modified
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `sub_filter_last_modified` `on` | `off`; |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию | `sub_filter_last_modified off;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Позволяет сохранить поле заголовка `Last-Modified` исходного ответа во время замены для лучшего кэширования ответов.
По умолчанию поле заголовка удаляется, так как содержимое ответа изменяется во время обработки.
### sub_filter_once
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `sub_filter_once` `on` | `off`; |
|------------------------------------------------------------------------------------------|-----------------------------------|
| По умолчанию | `sub_filter_once on;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Определяет, сколько раз нужно искать каждую из заменяемых строк: один раз или многократно.
### sub_filter_types
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `sub_filter_types` mime-тип ...; |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию | `sub_filter_types text/html;` |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
Разрешает замену строк в ответах с указанными MIME-типами в дополнение к `text/html`. Специальное значение "\*" соответствует любому MIME-типу.
# https://angie.software/adc/docs/load_balancer/reference/http/http_upstream.md
# Upstream
Предоставляет контекст для описания группы серверов, которые могут использоваться в директивах [proxy_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-pass), [fastcgi_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_fastcgi.md#adc-fastcgi-pass), [uwsgi_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_uwsgi.md#adc-uwsgi-pass), [scgi_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_scgi.md#adc-scgi-pass), [memcached_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_memcached.md#adc-memcached-pass) и [grpc_pass](https://angie.software//adc/docs/load_balancer/reference/http/http_grpc.md#adc-grpc-pass).
## Пример конфигурации
```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;
}
}
```
## Директивы
### backup_switch
| [Синтаксис](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 {
zone my_backend 1m;
server primary1.example.com;
server primary2.example.com;
server backup1.example.com backup;
server backup2.example.com backup;
backup_switch permanent=2m;
}
```
Если балансировщик переключается с основных серверов на резервную группу,
все последующие запросы обрабатываются этой резервной группой в течение 2 минут.
По истечении 2 минут балансировщик повторно проверяет основные серверы
и снова делает их активными, если они работают нормально.
### bind_conn
| [Синтаксис](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](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#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 {
zone ntlm_backend 1m;
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 "";
# ...
}
}
```
### feedback
| [Синтаксис](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` механизм балансировки нагрузки по обратной связи.
Он динамически корректирует решения при балансировке,
умножая вес каждого проксируемого сервера на среднее значение обратной связи,
которое меняется с течением времени в зависимости от значения переменной
и подчиняется необязательному условию.
Могут быть заданы следующие параметры:
| `переменная` | Переменная, из которой берется значение обратной связи.
Она должна представлять собой метрику производительности или состояния;
предполагается, что сервер передает ее в заголовках или иным образом.
Значение оценивается при каждом ответе от сервера
и учитывается в скользящем среднем
согласно настройкам `inverse` и `factor`. |
|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `inverse` | Если параметр задан, значение обратной связи интерпретируется наоборот:
более низкие значения указывают на лучшую производительность. |
| `factor` | Коэффициент, по которому значение обратной связи учитывается
при расчете среднего.
Допустимы целые числа от 0 до 99.
По умолчанию — `90`.
Среднее рассчитывается по формуле [экспоненциального сглаживания](https://ru.wikipedia.org/wiki/Экспоненциальное_сглаживание).
Чем больше коэффициент, тем меньше новые значения влияют на среднее;
если указать `90`, то будет взято 90 % от предыдущего значения
и лишь 10 % от нового. |
| `account` | Указывает условную переменную,
которая контролирует, какие ответы учитываются при расчете.
Среднее значение обновляется с учетом значения обратной связи из ответа,
только если условная переменная этого ответа
не равна `""` или `"0"`.
#### NOTE
По умолчанию ответы в ходе [активных проверок](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)
не включаются в расчет;
комбинация переменной [$upstream_probe](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe)
с `account` позволяет включить эти ответы
или даже исключить все остальное. |
| `last_byte` | Позволяет обрабатывать данные от проксируемого сервера после получения
полного ответа, а не только заголовка. |
Пример:
```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`
или ответы на обычные клиентские запросы.
### 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.
### 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 {
zone backend 1m;
ip_hash;
server backend1.example.com;
server backend2.example.com;
server backend3.example.com down;
server backend4.example.com;
}
```
### 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 {
zone memcached_backend 1m;
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//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-http-version) следует установить в "1.1", а поле заголовка `Connection` — очистить:
```nginx
upstream http_backend {
zone http_backend 1m;
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//adc/docs/load_balancer/reference/http/http_fastcgi.md#adc-fastcgi-keep-conn):
```nginx
upstream fastcgi_backend {
zone fastcgi_backend 1m;
server 127.0.0.1:9000;
keepalive 8;
}
server {
#...
location /fastcgi/ {
fastcgi_pass fastcgi_backend;
fastcgi_keep_conn on;
# ...
}
}
```
#### NOTE
Протоколы SCGI и uwsgi не определяют семантику постоянных соединений.
### 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 |
Задает максимальное число запросов, которые можно сделать по одному постоянному соединению. После того как сделано максимальное число запросов, соединение закрывается.
Периодическое закрытие соединений необходимо для освобождения памяти, выделенной под конкретные соединения. Поэтому использование слишком большого максимального числа запросов может приводить к чрезмерному потреблению памяти и не рекомендуется.
### 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 |
Ограничивает максимальное время, в течение которого могут обрабатываться запросы в рамках постоянного соединения. По достижении заданного времени соединение закрывается после обработки очередного запроса.
### 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 |
Задает таймаут, в течение которого неактивное постоянное соединение с сервером группы не будет закрыто.
### least_bandwidth
| [Синтаксис](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | `least_bandwidth` `both` | `upstream` | `downstream` [`factor=`number]; |
|------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
| По умолчанию | `both` |
| [Контекст](https://angie.software//adc/docs/load_balancer/reference/configfile.md#adc-configfile) | upstream |
Модуль балансировки нагрузки `least_bandwidth` выбирает проксируемый сервер,
который использует наименьший объем пропускной способности,
стремясь равномерно распределить сетевой трафик,
направляя новые сессии на сервер с наименьшим потреблением пропускной способности.
Соответственно, чем меньше трафика, тем сервер считается менее загруженным
и тем больше запросов будет на него отправляться.
| `upstream` | Директива учитывает только пропускную способность, используемую **от клиента к серверу**. |
|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `downstream` | Директива учитывает только пропускную способность, используемую **от сервера к клиенту**. |
| `both` | Директива учитывает сумму пропускной способности, используемой
вверх (от клиента к серверу) и вниз по потоку (от сервера к клиенту).
Режим по умолчанию. |
| `factor` | Необязательный коэффициент сглаживания для расчета скользящего
среднего, в диапазоне от 0 до 100 (по умолчанию 90). Более высокий коэффициент
означает более медленную адаптацию к изменениям. |
Модуль периодически вычисляет среднее использование пропускной способности для
каждого проксируемого сервера, используя формулу скользящего среднего для
сглаживания колебаний со временем. Когда начинается новая сессия, он выбирает
проксируемый сервер с наименьшим средним использованием пропускной способности,
скорректированным с учетом веса сервера, если он указан. Если несколько серверов
имеют одинаковое минимальное среднее использование пропускной способности,
применяется взвешенный метод round-robin.
### 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) с учетом их весов.
### least_time
| [Синтаксис](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](#adc-u-response-time-factor),
и переопределяет его, если параметр задан. |
|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `account` | Указывает условную переменную,
которая контролирует, какие ответы учитываются при расчете.
Среднее значение обновляется,
только если условная переменная ответа
не равна `""` или `"0"`.
#### NOTE
По умолчанию ответы в ходе [активных проверок](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)
не включаются в расчет;
комбинация переменной [$upstream_probe](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe)
с `account` позволяет включить эти ответы
или даже исключить все остальное. |
Текущие значения представлены как `header_time` (только заголовки)
и `response_time` (ответы целиком) в объекте `health` сервера
среди [метрик апстрима](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-upstreams) в API.
### queue
Если для запроса не удается назначить проксируемый сервер с первой попытки
(например, при краткосрочном перебое в работе
или всплеске нагрузки с достижением предела [max_conns](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server)),
запрос не отклоняется;
вместо этого Angie пытается поставить его в очередь на обработку.
Численный параметр директивы задает максимальное количество запросов
в очереди [рабочего процесса](https://angie.software//angie/docs/configuration/modules/core.md#worker-processes).
Если очередь целиком заполнена,
клиенту отдается ошибка `502 (Bad Gateway)`.
#### NOTE
К запросам в очереди также применяется логика директивы
[proxy_next_upstream](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-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` должна использоваться после всех директив,
задающих тот или иной метод балансировки нагрузки, иначе она не будет
работать.
### 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](#adc-u-least-conn), при котором запрос передается на сервер с наименьшим количеством активных соединений.
### response_time_factor
| [Синтаксис](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](#adc-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//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-next-upstream),
[fastcgi_next_upstream](https://angie.software//adc/docs/load_balancer/reference/http/http_fastcgi.md#adc-fastcgi-next-upstream), [uwsgi_next_upstream](https://angie.software//adc/docs/load_balancer/reference/http/http_uwsgi.md#adc-uwsgi-next-upstream),
[scgi_next_upstream](https://angie.software//adc/docs/load_balancer/reference/http/http_scgi.md#adc-scgi-next-upstream), [memcached_next_upstream](https://angie.software//adc/docs/load_balancer/reference/http/http_memcached.md#adc-memcached-next-upstream) и
[grpc_next_upstream](https://angie.software//adc/docs/load_balancer/reference/http/http_grpc.md#adc-grpc-next-upstream). Кроме того, значение `header_time`
пересчитывается, только если получены и обработаны все заголовки, а
`response_time` — только если получен весь ответ.
### 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` и означает, что ограничения нет. Если группа не находится в [зоне разделяемой памяти](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone), то ограничение работает отдельно для каждого рабочего процесса. |
#### NOTE
При включенных [неактивных постоянных соединениях](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive), нескольких [рабочих процессах](https://angie.software//angie/docs/configuration/modules/core.md#worker-processes) и [зоне разделяемой памяти](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) суммарное число активных и неактивных соединений с проксируемым сервером может превышать значение `max_conns`.
`max_fails=`число — задает число неудачных попыток связи с сервером,
которые должны произойти в течение заданного [fail_timeout](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#fail-timeout)
времени для того, чтобы сервер считался недоступным;
после этого он будет повторно проверен через то же самое время.
Что считается неудачной попыткой,
определяется директивами [proxy_next_upstream](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-proxy-next-upstream),
[fastcgi_next_upstream](https://angie.software//adc/docs/load_balancer/reference/http/http_fastcgi.md#adc-fastcgi-next-upstream), [uwsgi_next_upstream](https://angie.software//adc/docs/load_balancer/reference/http/http_uwsgi.md#adc-uwsgi-next-upstream),
[scgi_next_upstream](https://angie.software//adc/docs/load_balancer/reference/http/http_scgi.md#adc-scgi-next-upstream), [memcached_next_upstream](https://angie.software//adc/docs/load_balancer/reference/http/http_memcached.md#adc-memcached-next-upstream) и
[grpc_next_upstream](https://angie.software//adc/docs/load_balancer/reference/http/http_grpc.md#adc-grpc-next-upstream).
При превышении `max_fails` сервер также признается неработающим с точки зрения
[upstream_probe](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream_probe.md#adc-u-upstream-probe); клиентские запросы не будут направляться к нему,
пока проверки не признают его работающим.
#### NOTE
Если директива `server` в группе разрешается в несколько серверов,
ее настройка `max_fails` применяется к каждому серверу отдельно.
Если после разрешения всех директив `server`
в апстриме остается только один сервер,
настройка `max_fails` не действует и будет проигнорирована.
| `max_fails=1` | Число попыток по умолчанию; |
|-----------------|-------------------------------|
| `max_fails=0` | Отключает учет попыток. |
`fail_timeout=`время — задает период времени, в течение которого
должно произойти определенное число неудачных попыток связи с сервером
([max_fails](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails)), чтобы сервер считался недоступным.
Затем сервер остается недоступным в течение того же самого времени,
прежде чем будет проверен повторно.
Значение по умолчанию — 10 секунд.
#### NOTE
Если директива `server` в группе разрешается в несколько серверов,
ее настройка `fail_timeout` применяется к каждому серверу отдельно.
Если после разрешения всех директив `server`
в апстриме остается только один сервер,
настройка `fail_timeout` не действует и будет проигнорирована.
| `backup` | Помечает сервер как запасной (создается отдельная группа резервирования серверов).
На этот сервер будут передаваться запросы в случае, если не работает вся основная группа серверов.
Можно создать несколько групп резервирования серверов и задать уровень
для каждой группы с помощью `backup=<уровень_группы>`. Например,
`backup=1` (или просто `backup`) — группа резервных серверов первого уровня,
(в API отображается как `true`), `backup=2` — группа резервных серверов второго уровня,
(в API отображается как соответствующее число).
Если директива `server` использует SRV-записи DNS
для получения адресов проксируемых серверов,
то уровень группы резервирования можно задать с помощью параметра `backup=prio`.
В этом случае абсолютное значение приоритета `priority=n` из SRV-записи будет использовано
в качестве уровня резервной группы: `backup=n`.
Если параметр `backup=prio` не задан, уровень резервирования будет определяться
через относительное значение приоритета `priority=n` из SRV-записи.
В этом случае директива `backup=n` задает базовый уровень отсчета (например `backup=3`),
а относительные уровни резервирования отсчитываются от этого уровня.
Сервер с наименьшим значением `priority` получит уровень `backup=3`,
следующий за ним — `backup=4` и так далее. Если уровень отсчета `backup=n` не задан,
отсчет будет идти от нуля: сервер с наименьшим значением `priority`
получит `backup=0` и станет основным, за ним — `backup=1`, резервный, и так далее.
Если задана директива [backup_switch](#adc-u-backup-switch),
также применяется ее логика активного резервирования. |
|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `down` | Помечает сервер как постоянно недоступный. |
| `drain` | Помечает сервер как разгружаемый (draining); это значит,
что он получает только запросы сессий,
привязанных ранее через [sticky](#adc-u-sticky).
В остальном поведение такое же, как в режиме `down`. |
#### WARNING
Параметр `backup` нельзя использовать совместно с методами
балансировки нагрузки [hash](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-hash), [ip_hash](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-ip-hash) и
[random](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-random).
Параметры `down` и `drain` взаимно исключающие.
| `resolve` | Позволяет отслеживать изменения списка IP-адресов, соответствующего
доменному имени, и обновлять его без перезагрузки конфигурации.
При этом группа должна находиться в
[зоне разделяемой памяти](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone);
также должен быть определен
[преобразователь имен в адреса](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver). |
|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `service=`имя | Включает преобразование SRV-записей DNS и задает имя сервиса. Для
работы параметра необходимо задать параметр `resolve` у сервера,
не указывая порт сервера при имени хоста.
Если в имени службы нет точек, формируется имя по стандарту RFC:
к имени службы добавляется префикс `_`,
затем через точку добавляется `_tcp`.
Так, имя службы `http` даст в результате `_http._tcp`.
Angie разрешает SRV-записи,
объединяя нормализованное имя службы и имя хоста
и получая список серверов для полученной комбинации через DNS,
вместе с их приоритетами и весами.
- SRV-записи с наивысшим приоритетом
(те, которые имеют минимальное значение приоритета)
разрешаются как основные серверы,
а прочие записи становятся запасными серверами.
Если `backup` установлено с `server`,
SRV-записи с наивысшим приоритетом разрешаются как запасные серверы,
а прочие записи игнорируются.
- Вес аналогичен параметру `weight` директивы `server`.
Если вес задан как в самой директиве, так и в SRV-записи,
используется вес, установленный в директиве. |
В этом примере выполняется поиск записи `_http._tcp.backend.example.com`:
```nginx
server backend.example.com service=http resolve;
```
| `sid=`id | Задает ID сервера в группе. Если параметр не задан,
то ID задается как шестнадцатеричный MD5-хэш
IP-адреса и порта или пути UNIX-сокета. |
|------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| `slow_start=`время | Задает [время](https://angie.software//angie/docs/configuration/configfile.md#syntax) восстановления веса сервера,
возвращающегося к работе
при балансировке нагрузки методом
[round-robin](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#round-robin) или [least_conn](#adc-u-least-conn).
Если параметр задан
и сервер после сбоя снова считается работающим
с точки зрения [max_fails](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) и [upstream_probe](https://angie.software//adc/docs/load_balancer/reference/http/http_upstream_probe.md#adc-u-upstream-probe),
то такой сервер равномерно набирает указанный для него вес
в течение заданного времени.
Если параметр не задан,
то в аналогичной ситуации
сервер сразу начинает работу с указанным для него весом. |
|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### NOTE
Если в апстриме задан только один `server`,
`slow_start` не работает и будет игнорироваться.
### state
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `state` файл; |
|------------------------------------------------------------------------------------------|-----------------|
| По умолчанию | — |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | upstream |
Указывает файл, где постоянно хранится список серверов апстрима.
Для хранения таких файлов специально создается каталог
`/var/lib/angie/state/`
с соответствующими правами доступа,
и в конфигурации остается добавить лишь имя файла:
```nginx
upstream backend {
zone backend 1m;
state /var/lib/angie/state/<ИМЯ ФАЙЛА>;
}
```
Список серверов здесь имеет формат, аналогичный `server`.
Содержимое файла изменяется при любом изменении серверов в разделе
[/config/http/upstreams/](https://angie.software//adc/docs/load_balancer/reference/http/http_api.md#adc-api-config-http-upstreams-servers)
через API конфигурации.
#### WARNING
Чтобы использовать директиву `state` в блоке `upstream`,
в нем не должно быть директив `server`,
но нужна зона разделяемой памяти ([zone](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone)).
### sticky
| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `sticky` cookie name [attr=значение]...;
`sticky route` значение...;
`sticky learn` `zone=`зона `create=`$create_var1... `lookup=`$lookup_var1... [`header`] [`norefresh`] [`timeout=`время];
`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`
в блоке [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server).
#### WARNING
Директива `sticky` должна использоваться после всех директив,
задающих тот или иной метод балансировки нагрузки,
иначе она не будет работать.
Если она используется наряду с директивой [bind_conn](#adc-u-bind-conn),
то `bind_conn` должна стоять после `sticky`.
Режим `cookie`
Этот режим использует cookie для хранения сессий.
Он подходит для ситуаций,
когда cookie уже используются для управления сессиями.
Здесь запрос от клиента,
пока не привязанного к какому-то серверу,
отправляется на сервер,
выбираемый согласно настроенному методу балансировки.
При этом Angie устанавливает cookie
с уникальным значением, идентифицирующим сервер.
Имя cookie (`name`) задается директивой `sticky`,
а значение (`value`) соответствует
параметру [sid](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve)
директивы [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server).
Учтите, что параметр дополнительно хэшируется,
если задана директива [sticky_secret](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky-secret).
Последующие запросы от клиента, содержащие такой cookie,
передаются на сервер, заданный значением cookie,
то есть сервер с указанным [sid](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve).
Если выбрать сервер не удается
или выбранный сервер не может обработать запрос,
то будет выбран другой сервер
согласно настроенному методу балансировки.
Директива позволяет назначать атрибуты такого cookie;
единственный атрибут, устанавливаемый по умолчанию, — `path=/`.
Значения атрибутов задаются строками с переменными.
Чтобы удалить атрибут, задайте для него пустое значение: `attr=`.
Так, `sticky cookie path=` задает cookie без атрибута `path`.
Здесь Angie создает cookie `srv_id` со сроком действия в 1 час
и доменом, заданным переменной:
```nginx
upstream backend {
zone backend 1m;
server backend1.example.com:8080;
server backend2.example.com:8080;
sticky cookie srv_id domain=$my_domain max-age=3600;
}
```
Режим `route`
Этот режим использует предопределенные идентификаторы маршрутов,
которые могут быть встроены в URL, cookie или другие свойства запроса.
Он менее гибок, так как зависит от предопределенных значений,
но лучше подходит, если такие идентификаторы уже используются.
Здесь проксируемый сервер при получении запроса
может назначить клиенту маршрут и вернуть его идентификатор способом,
известным им обоим.
В качестве идентификатора маршрута
должно использоваться значение параметра [sid](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve)
директивы [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server).
Учтите, что параметр дополнительно хэшируется,
если задана директива [sticky_secret](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#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](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve)
директивы [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server).
Если выбрать сервер не удается
или выбранный сервер не может обработать запрос,
то будет выбран другой сервер
согласно настроенному методу балансировки.
Здесь Angie ищет идентификатор маршрута в cookie `route`,
затем в аргументе запроса `route`:
```nginx
upstream backend {
zone backend 1m;
server backend1.example.com:8080 "sid=server 1";
server backend2.example.com:8080 "sid=server 2";
sticky route $cookie_route $arg_route;
}
```
Режим `learn`
В этом режиме для привязки клиента к конкретному проксируемому серверу
используется динамически генерируемый ключ;
этот режим более гибок,
так как назначает серверы на ходу,
хранит сеансы в зоне разделяемой памяти
и поддерживает различные способы передачи идентификаторов сессий.
Здесь сессия создается
на основе ответа проксируемого сервера.
С параметрами `create` и `lookup` перечисляются переменные,
указывающие, как создаются новые и ищутся существующие сессии.
Оба параметра можно использовать по нескольку раз.
Идентификатором сессии служит значение первой непустой переменной,
указанной с `create`;
например, это может быть
[cookie с проксируемого сервера](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#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 {
zone backend 1m;
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`
Параметры `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](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-sticky-sessid));
- идентификатор предварительно выбранного *сервера*:
значение параметра `sid=` из директивы `server`,
если оно задано,
либо MD5-хэш имени сервера
(в конфигурации это переменная
[$sticky_sid](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#v-sticky-sid)).
Проще всего можно передать эти идентификаторы через HTTP-заголовки
с помощью [proxy_set_header](https://angie.software//adc/docs/load_balancer/reference/http/http_proxy.md#adc-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](#adc-u-upstream):
- Cерверы, помеченные как `down` или временно недоступные из-за сбоев,
исключаются из выбора.
- Cерверы, которые достигли максимального количества соединений
(при использовании `max_conns`), временно пропускаются.
- Cерверы с опцией `drain`
могут быть выбраны для создания новых сессий в режиме `sticky`
при совпадении идентификаторов.
- Если ранее недоступный сервер восстанавливается,
`sticky` автоматически возобновляет его использование.
Поведение `sticky` можно дополнительно настроить
директивами [sticky_secret](#adc-u-sticky-secret) и [sticky_strict](#adc-u-sticky-strict).
Если в ходе работы `sticky` выбрать сервер не удается или он недоступен,
запрос будет обработан согласно выбранному методу балансировки нагрузки,
если только не включена директива `sticky_strict`.
В режиме `sticky_strict on;` запрос отклоняется с ошибкой.
Зоны разделяемой памяти,
указываемые в параметре `zone` директивы `sticky`,
не могут использоваться совместно различными `upstream`;
каждая группа должна использовать свою собственную зону.
### 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](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) в режимах `cookie` и `route`.
Строка может содержать переменные, например `$remote_addr`:
```nginx
upstream backend {
zone backend 1m;
server backend1.example.com:8080;
server backend2.example.com:8080;
sticky cookie cookie_name;
sticky_secret my_secret.$remote_addr;
}
```
Соль добавляется после хэшируемого значения;
чтобы независимо проверить механизм хэширования:
```console
$ echo -n "" | md5sum
```
