API#

Модуль API реализует HTTP RESTful интерфейс для получения базовой информации о веб-сервере в формате JSON, а также статистики по клиентским соединениям, зонам разделяемой памяти, DNS-запросам, HTTP-запросам, кэшу HTTP-ответов, сессиям модуля stream и зонам модулей limit_conn http, limit_conn stream, limit_req и http upstream, а также информацию о сертификатах, заданных в конфигурации и полученных ACME-клиентами.

Примечание

Живой пример вывода API доступен по адресу https://console.angie.software/api/.

Интерфейс принимает HTTP-методы GET и HEAD; запрос с другим методом вызовет ошибку:

{
    "error": "MethodNotAllowed",
    "description": "The POST method is not allowed for the requested API element \"/\"."
}

Директивы#

api#

Синтаксис	`api` путь;
По умолчанию	—
Контекст	location

Включает HTTP RESTful интерфейс в location.

Параметр путь является обязательным. Подобно директиве alias, задает путь для замены указанного в location, но по дереву API, а не файловой системы.

Если указан в префиксном location:

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:

location ~^/api/([^/]+)/(.*)$ {
    api /status/http/$1_zones/$2;
}

Здесь параметр путь определяет полный путь к элементу API; так, из запроса к /api/location/data/ будут выделены переменные:

$1 = "location"
$2 = "data/"

И конечный запрос будет иметь вид /status/http/location_zones/data/.

Также параметр путь позволяет управлять доступом к API:

location /status/ {
    api /status/;

    allow 127.0.0.1;
    deny  all;
}

Или же:

location /blog/requests/ {
    api /status/http/server_zones/blog/requests/;

    auth_basic           "blog";
    auth_basic_user_file conf/htpasswd;
}

Примечание

Если api стоит в location с косой чертой в конце префикса (например, location /name/), и при этом в директиве auto_redirect указано default, запросы без косой черты в конце будут перенаправляться (/name -> /name/).

api_config_files#

Синтаксис	`api_config_files` `on` \| `off`;
По умолчанию	off
Контекст	location

Включает или отключает добавление объекта config_files, перечисляющего содержимое всех файлов конфигурации Angie, загруженных сейчас экземпляром сервера, в состав раздела API /status/angie/. Например, при такой конфигурации:

location /status/ {
    api /status/;
    api_config_files on;
}

Запрос к /status/angie/ возвращает приблизительно следующее:

{
    "version":"1.12.1",
    "address":"192.168.16.5",
    "generation":1,
    "load_time":"2026-07-17T12:58:39.789Z",
    "config_files": {
        "/etc/angie/angie.conf": "...",
        "/etc/angie/mime.types": "..."
    }
}

По умолчанию вывод отключен, так как файлы конфигурации могут содержать особо чувствительные, конфиденциальные сведения.

Метрики#

Angie публикует статистику использования в разделе API /status/; открыть доступ к ней можно, задав соответствующий location. Полный доступ:

location /status/ {
    api /status/;
}

Пример частичного доступа, уже приводившийся выше:

location /stats/ {
    api /status/http/server_zones/;
}

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

С конфигурацией, включающей location /status/, зоны resolver, http в upstream, http server, location, cache, limit_conn в http и limit_req:

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

{
    "angie": {
        "version":"1.12.1",
        "address":"192.168.16.5",
        "generation":1,
        "load_time":"2026-07-17T12: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,
                            "header_time":21,
                            "response_time":42
                        },

                        "sid":"<server_id>"
                    }
                },

                "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, построив соответствующий запрос. Например:

$ 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/<http_server_zone>
$ curl https://www.example.com/status/http/server_zones/<http_server_zone>/ssl

Аргументы запроса#

Ответы API в формате JSON можно изменять с помощью следующих аргументов строки запроса:

pretty

По умолчанию API форматирует ответы JSON с отступами и переносами строк. Чтобы получить компактный однострочный вывод, добавьте pretty=off к строке запроса:

$ curl https://www.example.com/status/connections?pretty=off

  {"accepted":2257,"dropped":0,"active":3,"idle":1}

date

По умолчанию модуль использует для дат строки в формате ISO 8601; чтобы вместо этого использовать целочисленный формат эпохи UNIX, добавьте date=epoch к строке запроса:

$ 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

defaults

Получить параметры по умолчанию можно с аргументом defaults=on:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers?defaults=on

{
    "backend.example.com": {
        "weight": 1,
        "max_conns": 5,
        "max_fails": 1,
        "fail_timeout": 10,
        "slow_start": 0,
        "backup": false,
        "down": false,
        "sid": ""
    }
}

Состояние сервера#

`/status/angie`#

{
    "version": "1.12.1",
    "build_time": "2026-07-17T16:05:43.805Z",
    "address": "192.168.16.5",
    "generation": 1,
    "load_time": "2026-07-17T16:15:43.805Z"
    "config_files": {
        "/etc/angie/angie.conf": "...",
        "/etc/angie/mime.types": "..."
    }
}

`version`	Строка; версия запущенного сервера Angie
`build`	Строка; сборка, если указана при компиляции
`build_time`	Строка; время сборки исполняемого файла Angie в формате даты
`address`	Строка; адрес сервера, принявшего запрос к API
`generation`	Число; версия (поколение) конфигурации, отсчитываемая с последнего запуска Angie
`load_time`	Строка; время последней перезагрузки конфигурации в формате даты; строковые значения даются с миллисекундным разрешением
`config_files`	Объект; его члены — абсолютные имена всех файлов конфигурации Angie, загруженных сейчас экземпляром сервера, а их значения — строковые представления содержимого файлов, например: { "/etc/angie/angie.conf": "server {\n listen 80;\n # ...\n\n}\n" } Предупреждение Объект `config_files` есть в `/status/angie/`, только если включена директива api_config_files.

`/status/angie/license`#

{
    "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`#

{
  "accepted": 2257,
  "dropped": 0,
  "active": 3,
  "idle": 1
}

`accepted`	Число; суммарное количество принятых клиентских соединений
`dropped`	Число; суммарное количество сброшенных клиентских соединений
`active`	Число; текущее количество активных клиентских соединений
`idle`	Число; текущее количество бездействующих клиентских соединений

Зоны разделяемой памяти с распределением slab#

`/status/slabs/<зона>`#

Статистика для зон разделяемой памяти с распределением slab. Учитывается любая зона, использующая распределение slab, в том числе зоны limit_conn, limit_req, HTTP cache, а также зона разделяемой памяти HTTP или stream апстрима:

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`	Число; количество неудавшихся попыток выделения памяти указанного размера

Пример:

{
  "pages": {
    "used": 2,
    "free": 506
  },

  "slots": {
    "64": {
      "used": 1,
      "free": 63,
      "reqs": 1,
      "fails": 0
  }
}

DNS-запросы к резолверу#

`/status/resolvers/<зона>`#

Для сбора статистики в директиве resolver нужно задать параметр status_zone (HTTP или Stream):

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

Примечание

queries и responses учитывают каждый запрос на разрешение имён, который Angie выполняет внутренне, включая ответы из TTL-кэша. sent учитывает пакеты, фактически отправленные на сервер имён; разница между ними отражает обращения к кэшу.

Коды ответов описаны в RFC 1035, часть 4.1.1.

Различные типы DNS-записей описаны в RFC 1035, RFC 2782 и RFC 3596.

Пример:

{
  "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 нужно задать директиву status_zone:

server {
    ...
    status_zone server_zone;
}

Для группировки метрик по пользовательскому значению используйте альтернативный синтаксис. В этом примере метрики агрегируются по $host, и каждая группа выводится как отдельная зона:

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`	Объект; метрики ответов
`<code>`	Число; ненулевое количество ответов со статусом <code> (100-599)
`xxx`	Число; ненулевое количество ответов с другим кодом статуса
`data`	Объект; метрики данных
`received`	Число; суммарное количество байт, полученное от клиентов
`sent`	Число; суммарное количество байт, отправленное клиентам

Примечание

Счетчики responses учитывают только реальные ответы, фактически отправленные клиенту. Запрос, обработка которого завершилась без отправки ответа, считается в discarded и не увеличивает счетчики responses. В частности, 499 — это не ответ, а служебный внутренний код, который записывается только в журнал доступа и сигнализирует о том, что обработка запроса прекратилась без отправки ответа; такие запросы попадают в discarded, но никогда в responses.

Пример:

{
    "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 или if в location нужно задать директиву status_zone:

location / {
    root /usr/share/angie/html;
    status_zone location_zone;

    if ($request_uri ~* "^/condition") {
        # ...
        status_zone if_location_zone;
    }
}

Для группировки метрик по пользовательскому значению используйте альтернативный синтаксис. В этом примере метрики агрегируются по $host, и каждая группа выводится как отдельная зона:

status_zone $host zone=server_zone:5;

В указанной таким образом зоне разделяемой памяти будет собираться следующая статистика:

`requests`	Объект; метрики запросов
`total`	Число; суммарное количество клиентских запросов
`discarded`	Число; суммарное количество запросов завершенных без отправки ответа
`responses`	Объект; метрики ответов
`<code>`	Число; ненулевое количество ответов со статусом <code> (100-599)
`xxx`	Число; ненулевое количество ответов с другим кодом статуса
`data`	Объект; метрики данных
`received`	Число; суммарное количество байт, полученное от клиентов
`sent`	Число; суммарное количество байт, отправленное клиентам

Примечание

Счетчики responses учитывают только реальные ответы, фактически отправленные клиенту. Запрос, обработка которого завершилась без отправки ответа, считается в discarded и не увеличивает счетчики responses. В частности, 499 — это не ответ, а служебный внутренний код, который записывается только в журнал доступа и сигнализирует о том, что обработка запроса прекратилась без отправки ответа; такие запросы попадают в discarded, но никогда в responses.

Пример:

{
  "requests": {
    "total": 4158,
    "discarded": 0
  },

  "responses": {
    "200": 4157,
    "304": 1
  },

  "data": {
    "received": 538200,
    "sent": 177606236
  }
}

`/status/http/metric_zones/<зона>`#

Пользовательские метрики, созданные директивами metric_zone или metric_complex_zone в контексте http. Метрики обновляются через директиву metric или переменные модуля.

`discarded`	Число; количество отброшенных записей метрик из-за нехватки памяти в зоне.
`metrics`	Объект; метрики по ключам. Для зон с одной метрикой значения — числа. Для сложных зон значения — объекты с именами метрик. Для режима `histogram` значения — объекты с именами бакетов.

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

Пример:

{
    "discarded": 3,
    "metrics": {
        "example.com": {
            "count": 42,
            "max": 8
        }
        "expired": {
            "count": 10,
            "max": 3.2
        }
    }
}

Stream server#

`/status/stream/server_zones/<зона>`#

Для сбора статистики в контексте server нужно задать директиву status_zone:

server {
    ...
    status_zone server_zone;
}

Для группировки метрик по пользовательскому значению используйте альтернативный синтаксис. В этом примере метрики агрегируются по $server_addr, и каждая группа выводится как отдельная зона:

status_zone $server_addr 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`	Число; суммарное количество байт, отправленное клиентам

Пример:

{
  "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
  }
}

`/status/stream/metric_zones/<зона>`#

Пользовательские метрики, созданные директивами metric_zone или metric_complex_zone в контексте stream. Метрики обновляются через директиву metric или переменные модуля.

`discarded`	Число; количество отброшенных записей метрик из-за нехватки памяти в зоне.
`metrics`	Объект; метрики по ключам. Для зон с одной метрикой значения — числа. Для сложных зон значения — объекты с именами метрик. Для режима `histogram` значения — объекты с именами бакетов.

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

Пример:

{
    "discarded": 3,
    "metrics": {
        "127.0.0.1": {
            "count": 42,
            "max": 8
        },
        "expired": {
            "count": 10,
            "max": 3.2
        }
    }
}

HTTP caches#

proxy_cache cache_zone;
proxy_cache_valid 200 10m;

`/status/http/caches/<cache>`#

Для каждой зоны, сконфигурированной в proxy_cache, хранятся следующие данные:

{
  "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)
`responses`	Число; суммарное количество ответов, прочитанных из кэша
`bytes`	Число; суммарное количество байт, прочитанных из кэша
`stale`	Объект; метрики просроченных ответов, возвращенных из кэша (proxy_cache_use_stale)
`responses`	Число; суммарное количество ответов, прочитанных из кэша
`bytes`	Число; суммарное количество байт, прочитанных из кэша
`updating`	Объект; метрики просроченных ответов, возвращенных из кэша, пока данные в кэше обновляются (proxy_cache_use_stale updating)
`responses`	Число; суммарное количество ответов, прочитанных из кэша
`bytes`	Число; суммарное количество байт, прочитанных из кэша
`revalidated`	Объект; метрики просроченных и ревалидированных ответов, возвращенных из кэша (proxy_cache_revalidate)
`responses`	Число; суммарное количество ответов, прочитанных из кэша
`bytes`	Число; суммарное количество байт, прочитанных из кэша
`miss`	Объект; метрики ответов, не найденных в кэше
`responses`	Число; суммарное количество соответствующих ответов
`bytes`	Число; суммарное количество байт, прочитанных с проксируемого сервера
`responses_written`	Число; суммарное количество ответов, записанных в кэш
`bytes_written`	Число; суммарное количество байт, записанных в кэш
`expired`	Объект; количество ответов, возвращенных не из кэша, т.к. просрочены
`responses`	Число; суммарное количество соответствующих ответов
`bytes`	Число; суммарное количество байт, прочитанных с проксируемого сервера
`responses_written`	Число; суммарное количество ответов, записанных в кэш
`bytes_written`	Число; суммарное количество байт, записанных в кэш
`bypass`	Объект; статистика ответов, возвращенных в обход кэша (proxy_cache_bypass)
`responses`	Число; суммарное количество соответствующих ответов
`bytes`	Число; суммарное количество байт, прочитанных с проксируемого сервера
`responses_written`	Число; суммарное количество ответов, записанных в кэш
`bytes_written`	Число; суммарное количество байт, записанных в кэш

`shards`	Объект; его члены — отдельные шарды
`<shard>`	Объект; представляет отдельный шард, а имя объекта — путь кэша
`size`	Число; текущий размер шарда
`max_size`	Число; максимальный размер шарда, если задан в конфигурации
`cold`	Логическое значение; `true`, пока загрузчик кэша подгружает данные с диска

{
  "name_zone": {
    "shards": {
        "/path/to/shard1": {
            "size": 0,
            "cold": false
        },

        "/path/to/shard2": {
            "size": 0,
            "cold": false
        }
    }
}

ACME-клиенты#

`/status/http/acme_clients/<клиент>`#

Для каждого настроенного acme_client в блоке http возвращается текущее состояние клиента и сертификата:

{
  "state": "ready",
  "certificate": "valid",
  "details": "The client is ready to request a certificate.",
  "next_run": "2026-07-17T16:15:43.805Z"
}

`state`	Строка; состояние ACME-клиента. Возможные значения: `ready`, `requesting`, `disabled`, `failed`.
`certificate`	Строка; состояние сертификата. Возможные значения: `valid`, `expired`, `missing`, `mismatch`, `error`.
`details`	Строка; краткие сведения о последнем действии ACME.
`next_run`	Дата; ближайшая запланированная попытка запроса или обновления сертификата. Не возвращается, когда `state` равно `disabled` или `requesting`.

limit_conn#

limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m;

`/status/http/limit_conns/<зона>`, `/status/stream/limit_conns/<зона>`#

Каждая из сконфигурированных зон: limit_conn в http или limit_conn в stream содержит следующие данные:

{
  "passed": 73,
  "skipped": 0,
  "rejected": 0,
  "exhausted": 0
}

`passed`	Число; суммарное количество переданных на проксируемый сервер соединений
`skipped`	Число; суммарное количество соединений, переданных с нулевым или превосходящим 255 байт <key>
`rejected`	Число; суммарное количество соединений сверх сконфигурированного ограничения
`exhausted`	Число; суммарное количество соединений, сброшенных из-за переполнения хранилища зоны

limit_req#

limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s;

`/status/http/limit_reqs/<зона>`#

Каждая из сконфигурированных зон limit_req cодержит следующие данные:

{
  "passed": 54816,
  "skipped": 0,
  "delayed": 65,
  "rejected": 26,
  "exhausted": 0
}

`passed`	Число; суммарное количество проксированых соединений
`skipped`	Число; суммарное количество соединений, переданных с нулевым или превосходящим 255 байт <key>
`delayed`	Число; суммарное количество задержанных соединений
`rejected`	Число; суммарное количество сброшенных соединений
`exhausted`	Число; суммарное количество соединений, сброшенных из-за переполнения хранилища зоны

HTTP upstream#

Чтобы включить сбор следующих метрик, задайте директиву zone в контексте upstream, например:

upstream upstream {
    zone upstream 256k;
    server backend.example.com service=_example._tcp resolve max_conns=5;
    keepalive 4;
}

Статистика использования памяти этой зоны доступна в разделе API /status/slabs/ под её именем.

`/status/http/upstreams/<upstream>`#

где <upstream> — имя апстрима, в конфигурации которого указана директива zone.

{
    "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,
                "header_time": 21,
                "response_time": 42
            },

            "sid": "<server_id>"
        }
    },

    "keepalive": 2
}

`peers`	Объект; содержит метрики всех пиров апстрима во вложенных объектах, имена которых — канонические представления адресов этих пиров. Внутри каждого вложенного объекта:
`server`	Строка; сервер, как он указан в директиве server
`service`	Строка; имя сервиса, указанное в директиве server, если сконфигурировано
`backup`	Логическое значение; `true` для backup-серверов.
`weight`	Число; сконфигурированный weight
`state`	Строка; текущее состояние пира, и какие запросы ему отправляются: `busy`: указывает, что число запросов на сервер достигло ограничения, заданного max_conns, и новые запросы на него не отправляются; `down`: отключен вручную, не отправляются никакие запросы; `draining`: аналогичен `down`, но отправляются запросы сессий, привязанных ранее через sticky; `recovering`: восстанавливается после сбоя согласно slow_start, отправляется все больше запросов; `unavailable`: достиг предела max_fails, отправляются пробные клиентские запросы с интервалом fail_timeout; `up`: работоспособен, запросы отправляются как обычно; Дополнительные состояния в Angie PRO: `checking`: настроен как `essential` и проверяется, отправляются только проверочные запросы; `unhealthy`: неработающий, отправляются только проверочные запросы.
`selected`	Объект; статистика выбора пиров
`current`	Число; текущее количество соединений к пиру
`total`	Число; общее количество запросов переданных пиру
`last`	Строка или число; время последнего выбора пира в формате даты
`max_conns`	Число; максимальное количество одновременных активных соединений к пиру, если сконфигурировано
`responses`	Объект; статистика ответов
`<code>`	Число; ненулевое количество ответов со статусом <code> (100-599)
`xxx`	Число; ненулевое количество ответов с другим кодом статуса
`data`	Объект; метрики данных
`received`	Число; суммарное количество байт, полученное от пира
`sent`	Число; суммарное количество байт, отправленное пиру
`health`	Объект; статистика по состоянию пира
`fails`	Число; общее количество неудачных попыток работы с пиром
`unavailable`	Число; столько раз пир становился `unavailable` по достижении значения max_fails
`downtime`	Число; суммарное время (в миллисекундах), в течение которого пир был недоступен для выбора как `unavailable`
`downstart`	Строка или число; время, когда пир стал `unavailable`, в формате даты. Поле присутствует, только пока пир находится в состоянии `unavailable`; в остальных случаях оно отсутствует
`header_time`	Число; среднее время (в миллисекундах) получения заголовков ответа от сервера; см. директиву response_time_factor
`response_time`	Число; среднее время (в миллисекундах) получения ответа от сервера; см. директиву response_time_factor
`sid`	Строка; id сервера, указанный в конфигурации апстрима
`feedback`	Число; текущее среднее значение обратной связи, используемое методом балансировки feedback, присутствует, только если используется этот метод
`keepalive`	Число; текущее количество кэшированных соединений
`backup_switch`	Объект; содержит текущее состояние логики активного резервирования, присутствует, если для апстрима настроен backup_switch (PRO)
`active`	Число; уровень активной группы, которая сейчас используется для балансировки запросов. Если активная группа является основной, значение равно 0
`timeout`	Число; оставшееся время ожидания в миллисекундах, после которого балансировщик перепроверит на наличие здоровых узлов группы с меньшим уровнем, начиная с основной, а группы с большим уровнем не проверяются; не отображается для основной группы (уровень 0)

`health/probes`#

Если для апстрима настроены проверки upstream_probe (PRO), то в объекте health также есть вложенный объект probes, содержащий счетчики проверок работоспособности сервера, а state, помимо значений из таблицы выше, может принимать значения checking и unhealthy:

{
    "192.168.16.4:80": {
        "state": "unhealthy",
        "...": "...",
        "health": {
            "...": "...",
            "probes": {
                "count": 10,
                "fails": 10,
                "last": "2026-07-17T09:56:07Z"
            }
        }
    }
}

Значение checking у state не учитывается в downtime и означает, что сервер, проверка которого настроена с параметром essential, еще не проверялся; значение unhealthy — что сервер неработающий. Оба эти состояния также означают, что сервер не участвует в балансировке. Детали проверок см. в описании upstream_probe.

Счетчики в probes:

`count`	Число; общее количество проверок этого сервера
`fails`	Число; количество неуспешных проверок
`last`	Строка или число; время последней проверки в формате даты

`queue`#

Если для апстрима настроена очередь запросов, то в объекте апстрима также есть вложенный объект queue, содержащий счетчики запросов в очереди:

{
    "queue": {
        "queued": 20112,
        "waiting": 1011,
        "dropped": 6031,
        "timedout": 560,
        "overflows": 13
    }
}

Значения счетчиков суммируются по всем рабочим процессам:

`queued`	Число; общее количество запросов, попавших в очередь
`waiting`	Число; текущее количество запросов в очереди
`dropped`	Число; общее количество запросов, удаленных из очереди из-за того, что клиент преждевременно закрыл соединение
`timedout`	Число; общее количество запросов, удаленных из очереди по таймауту
`overflows`	Число; общее количество случаев переполнения очереди

Stream upstream#

Чтобы включить сбор следующих метрик, задайте директиву zone в контексте upstream, например:

upstream upstream {
    zone upstream 256k;
    server backend.example.com service=_example._tcp resolve max_conns=5;
    keepalive 4;
}

Статистика использования памяти этой зоны доступна в разделе API /status/slabs/ под её именем.

`/status/stream/upstreams/<upstream>`#

Здесь <upstream> — имя апстрима, в конфигурации которого использована директива zone.

{
    "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,
                "connect_time": 3,
                "first_byte_time": 21,
                "last_byte_time": 42
            }
        }
    }
}

`peers`	Объект; содержит метрики всех пиров апстрима во вложенных объектах, имена которых — канонические представления адресов этих пиров. Внутри каждого вложенного объекта:
`server`	Строка; адрес, заданный директивой server
`service`	Строка; имя сервиса, если оно указано в директиве server
`backup`	Логическое значение; `true` для backup-серверов
`weight`	Число; заданный для пира вес
`state`	Строка; текущее состояние пира, и какие запросы ему отправляются: `busy`: указывает, что число запросов на сервер достигло ограничения, заданного max_conns, и новые запросы на него не отправляются; `down`: отключен вручную, не отправляются никакие запросы; `draining`: аналогичен `down`, но отправляются запросы сессий, привязанных ранее через sticky; `recovering`: восстанавливается после сбоя согласно slow_start, отправляется все больше запросов; `unavailable`: достиг предела max_fails, отправляются пробные клиентские запросы с интервалом fail_timeout; `up`: работоспособен, запросы отправляются как обычно. Дополнительные состояния в Angie PRO: `checking`: настроен как `essential` и проверяется, отправляются только проверочные запросы; `unhealthy`: неработающий, отправляются только проверочные запросы.
`selected`	Объект; статистика выбора этого пира для подключения
`current`	Число; текущее количество подключений к пиру
`total`	Число; общее количество подключений, направленных этому пиру
`last`	Строка или число; время, когда пир был выбран в последний раз, в формате даты
`max_conns`	Число; максимальное количество одновременных активных подключений к пиру, если оно задано
`data`	Объект; статистика передачи данных
`received`	Число; общее количество байт, полученное от пира
`sent`	Число; общее количество байт, отправленное пиру
`health`	Объект; статистика по состоянию пира
`fails`	Число; общее количество неудачных попыток связаться с пиром
`unavailable`	Число; общее количество переходов в состояние `unavailable` по достижении значения max_fails
`downtime`	Число; общее время в миллисекундах, в течение которого пир находился в состоянии `unavailable` (недоступен для выбора)
`downstart`	Строка или число; время, когда пир последний раз стал `unavailable`, в формате даты. Поле присутствует, только пока пир находится в состоянии `unavailable`; в остальных случаях оно отсутствует
`connect_time`	Число; среднее время (в миллисекундах) установления соединения с сервером; см. директиву response_time_factor
`first_byte_time`	Число; среднее время (в миллисекундах) получения первого байта ответа от сервера; см. директиву response_time_factor
`last_byte_time`	Число; среднее время (в миллисекундах) получения полного ответа от сервера; см. директиву response_time_factor
`feedback`	Число; текущее среднее значение обратной связи, используемое методом балансировки feedback, присутствует, только если используется этот метод
`backup_switch` (PRO 1.10.0+)	Объект; содержит текущее состояние логики активного резервирования, присутствует, если для апстрима настроен backup_switch (PRO)
`active`	Число; уровень активной группы, которая сейчас используется для балансировки запросов. Если активная группа является основной, значение равно 0
`timeout`	Число; оставшееся время ожидания в миллисекундах, после которого балансировщик перепроверит на наличие здоровых узлов группы с меньшим уровнем, начиная с основной, а группы с большим уровнем не проверяются; не отображается для основной группы (уровень 0)

{
    "192.168.16.4:80": {
        "state": "unhealthy",
        "...": "...",
        "health": {
            "...": "...",
            "probes": {
                "count": 2,
                "fails": 2,
                "last": "2026-07-17T11:03:54Z"
            }
        }
    }
}

Значение checking у state означает, что сервер, проверка которого настроена с параметром essential, еще не проверялся; значение unhealthy — что сервер неработающий. Оба эти состояния также означают, что сервер не участвует в балансировке. Детали проверок см. в описании upstream_probe.

Счетчики в probes:

`count`	Число; общее количество проверок этого сервера
`fails`	Число; количество неуспешных проверок
`last`	Строка или число; время последней проверки в формате даты

Сертификаты#

`/certificates/`#

Объект API верхнего уровня, отдельный от дерева статистики /status/, отображает TLS-сертификаты, загруженные Angie.

Сертификат не отображается в объекте static, если имя файла сертификата или ключа содержит переменную. В частности, это относится к сертификату, предоставленному ACME-клиентом через переменную $acme_cert_<имя>. Сертификат, используемый несколькими серверами, указывается один раз.

В следующем примере Angie загружает статический сертификат и получает еще один с помощью ACME-клиента. Для разрешения доменного имени сервера каталога ACME-клиенту требуется настроенная директива resolver:

http {
    resolver 127.0.0.53;

    acme_client example https://acme.example.com/directory;

    server {
        listen      443 ssl;
        server_name www.example.com;

        ssl_certificate     example.com.crt;
        ssl_certificate_key example.com.key;

        location /certificates/ {
            api /certificates/;
        }
    }

    server {
        listen      443 ssl;
        server_name acme.example.com;

        acme                example;
        ssl_certificate     $acme_cert_example;
        ssl_certificate_key $acme_cert_key_example;
    }
}

В ответ на запрос curl https://www.example.com/certificates/ Angie возвращает:

{
    "static": {
        "example.com.crt": {
            "key": "RSA (2048 bits)",
            "chain": [
                {
                    "subject": {
                        "common_name": "example.com",
                        "alt_names": [
                            "example.com",
                            "www.example.com"
                        ],
                        "organization": "Example, Inc."
                    },

                    "issuer": {
                        "common_name": "Example Root CA",
                        "country": "US",
                        "organization": "Example, Inc."
                    },

                    "validity": {
                        "since": "Sep 18 19:46:19 2022 GMT",
                        "until": "Jun 15 19:46:19 2025 GMT"
                    }
                }
            ]
        }
    },

    "acme_clients": {
        "example": {
            "key": "EC (prime256v1)",
            "chain": [
                {
                    "subject": {
                        "common_name": "acme.example.com"
                    },

                    "issuer": {
                        "common_name": "Example ACME CA"
                    },

                    "validity": {
                        "since": "Sep 18 19:46:19 2022 GMT",
                        "until": "Dec 17 19:46:19 2022 GMT"
                    }
                }
            ]
        }
    }
}

static

Объект; серверные сертификаты, заданные директивой ssl_certificate в HTTP-модуле, ssl_certificate в потоковом модуле или ssl_certificate в почтовом модуле; ключом каждого элемента служит имя файла сертификата. В сборках с --with-ntls объект также содержит сертификаты, заданные директивой proxy_ssl_certificate в HTTP или proxy_ssl_certificate в потоковом модуле для аутентификации на проксируемых серверах

acme_clients

Объект; доступен в сборках Angie с HTTP-модулем ACME, который также необходим для потокового модуля ACME. Содержит сертификаты, полученные ACME-клиентами для HTTP- и потоковых серверов; ключом каждого элемента служит имя acme_client. Отображаются только клиенты, уже получившие сертификат

Каждая запись в объектах static и acme_clients описывает один комплект сертификатов:

`key`	Строка; тип и размер (или кривая) закрытого ключа, например `RSA (2048 bits)`, `EC (prime256v1)` или `DH (2048 bits)`
`chain`	Массив; сертификаты комплекта, начиная с конечного (серверного) сертификата, затем промежуточные сертификаты, по направлению к корневому. Каждый элемент — объект, описывающий один сертификат:
`subject`	Объект; отличительное имя (DN) субъекта
`common_name`	Строка; Common Name (`CN`)
`alt_names`	Массив строк; DNS-имена и IP-адреса из расширения Subject Alternative Name
`country`	Строка; Country (`C`)
`state_or_province`	Строка; State or Province Name (`ST`)
`organization`	Строка; Organization (`O`)
`issuer`	Объект; отличительное имя (DN) издателя, с теми же полями, что и `subject`
`validity`	Объект; срок действия сертификата
`since`	Строка; начало срока действия (`notBefore`)
`until`	Строка; окончание срока действия (`notAfter`)

Поля вложенных объектов subject и issuer возвращаются, только если соответствующие значения есть в сертификате.

API динамической конфигурации#

В составе API есть раздел /config, позволяющий динамически менять конфигурацию Angie в формате JSON с помощью HTTP-запросов PUT, PATCH и DELETE. Все изменения атомарны: новые настройки применяются целиком либо не применяются вовсе. При ошибке Angie сообщит, в чем причина.

Подразделы `/config`#

Cейчас в разделе /config доступна настройка отдельных серверов в составе апстримов для модулей HTTP и stream; число настроек, к которым применима динамическая конфигурация, планомерно увеличивается.

`/config/http/upstreams/<upstream>/servers/<имя>`#

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

Параметры в составе пути URI:

<upstream>

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

<имя>

Имя конкретного сервера в составе указанного <upstream>; задается в формате <service>@<host>, где:

<service>@ — необязательная часть, задающая имя сервиса в целях разрешения SRV-записей.
<host> — доменное имя сервиса (при наличии resolve) или IP-адрес; также можно указать порт.

Например, для следующей конфигурации:

upstream backend {
    server backend.example.com service=_http._tcp resolve;
    server 127.0.0.1;
    zone backend 1m;
}

Допустимы такие имена серверов:

$ 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.

Примечание

Отдельного параметра drain здесь нет; включить режим drain можно, задав для down строковое значение drain:

$ curl -X PUT -d \"drain\" \
  http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/down

Пример:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on

{
    "weight": 1,
    "max_conns": 0,
    "max_fails": 1,
    "fail_timeout": 10,
    "slow_start": 0,
    "backup": true,
    "down": false,
    "sid": ""
}

Фактически доступны будут только те параметры, которые поддерживает текущий метод балансировки нагрузки апстрима. Так, если апстрим настроен с методом балансировки random:

upstream backend {
    zone backend 256k;
    server backend.example.com resolve max_conns=5;
    random;
}

То добавить в него новый сервер с параметром backup невозможно:

$ curl -X PUT -d '{ "backup": true }' \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend1.example.com

{
    "error": "FormatError",
    "description": "The \"backup\" field is unknown."
}

`/config/stream/upstreams/<upstream>/servers/<имя>`#

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

Параметры в составе пути URI:

<upstream>

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

<имя>

Имя конкретного сервера в составе указанного <upstream>; задается в формате <service>@<host>, где:

<service>@ — необязательная часть, задающая имя сервиса в целях разрешения SRV-записей.
<host> — доменное имя сервиса (при наличии resolve) или IP-адрес; также можно указать порт.

Например, для следующей конфигурации:

upstream backend {
    server backend.example.com:8080 service=_example._tcp resolve;
    server 127.0.0.1:12345;
    zone backend 1m;
}

Допустимы такие имена серверов:

$ 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.

Примечание

Отдельного параметра drain здесь нет; включить режим drain можно, задав для down строковое значение drain:

$ curl -X PUT -d \"drain\" \
  http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com/down

Пример:

$ curl http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com?defaults=on

{
    "weight": 1,
    "max_conns": 0,
    "max_fails": 1,
    "fail_timeout": 10,
    "slow_start": 0,
    "backup": true,
    "down": false,
}

Фактически доступны будут только те параметры, которые поддерживает текущий метод балансировки нагрузки апстрима. Так, если апстрим настроен с методом балансировки random:

upstream backend {
    zone backend 256k;
    server backend.example.com resolve max_conns=5;
    random;
}

То добавить в него новый сервер с параметром backup невозможно:

$ curl -X PUT -d '{ "backup": true }' \
    http://127.0.0.1/config/stream/upstreams/backend/servers/backend1.example.com

{
    "error": "FormatError",
    "description": "The \"backup\" field is unknown."
}

При удалении серверов можно установить аргумент connection_drop=<значение> , чтобы переопределить настройки proxy_connection_drop:

$ 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-методов на примере следующей конфигурации апстрима:

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/ допустимы такие запросы:

$ 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; см. Аргументы запроса.

PUT#

HTTP-метод PUT позволяет создать новую JSON-сущность по указанному пути или полностью заменить существующую.

Например, чтобы добавить не заданный ранее параметр max_fails у сервера backend.example.com в апстриме backend:

$ curl -X PUT -d '2' \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails

{
    "success": "Updated",
    "description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was updated with replacing."
}

Проверим изменения:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com

{
    "max_conns": 5,
    "max_fails": 2
}

DELETE#

HTTP-метод DELETE удаляет ранее заданные настройки по указанному пути; при этом восстанавливаются значения по умолчанию, если они есть.

Например, чтобы удалить измененный ранее параметр max_fails у сервера backend.example.com в апстриме backend:

$ curl -X DELETE \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails

{
    "success": "Reset",
    "description": "Configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was reset to default."
}

Проверим изменения с аргументом defaults=on:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on

{
    "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, grpc_connection_drop, fastcgi_connection_drop, scgi_connection_drop и uwsgi_connection_drop:

$ 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), отправив в данных JSON-определение.

Метод работает так: если сущности, указанные в новом определении, уже есть в конфигурации, они будут перезаписаны; если их нет, то они будут добавлены.

Например, чтобы поменять значение параметра down у сервера backend.example.com в апстриме backend, оставив прочее без изменений:

$ curl -X PATCH -d '{ "down": true }' \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com

{
    "success": "Updated",
    "description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging."
}

Проверим изменения:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com

{
    "max_conns": 5,
    "down": true
}

Обратите внимание, что переданный с запросом PATCH JSON-объект слился с уже существующим, а не заменил его целиком, как было бы с PUT.

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

Примечание

Такое удаление аналогично действию DELETE; в частности, восстанавливаются значения по умолчанию.

Например, чтобы удалить добавленный ранее параметр down и одновременно с этим изменить max_conns:

$ curl -X PATCH -d '{ "down": null, "max_conns": 6 }' \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com

{
    "success": "Updated",
    "description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging."
}

Проверим изменения:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com

{
    "max_conns": 6
}

Параметр down, для которого было передано значение null, удален; значение max_conns изменено.

API#

Директивы#

api#

api_config_files#

Метрики#

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

Аргументы запроса#

Состояние сервера#

/status/angie#

/status/angie/license#

Соединения#

/status/connections#

Зоны разделяемой памяти с распределением slab#

/status/slabs/<зона>#

DNS-запросы к резолверу#

/status/resolvers/<зона>#

HTTP server и location#

/status/http/server_zones/<зона>#

/status/http/location_zones/<зона>#

/status/http/metric_zones/<зона>#

Stream server#

/status/stream/server_zones/<зона>#

/status/stream/metric_zones/<зона>#

HTTP caches#

/status/http/caches/<cache>#

ACME-клиенты#

/status/http/acme_clients/<клиент>#

limit_conn#

/status/http/limit_conns/<зона>, /status/stream/limit_conns/<зона>#

limit_req#

/status/http/limit_reqs/<зона>#

HTTP upstream#

/status/http/upstreams/<upstream>#

health/probes#

queue#

Stream upstream#

/status/stream/upstreams/<upstream>#

Сертификаты#

/certificates/#

API динамической конфигурации#

Подразделы /config#

/config/http/upstreams/<upstream>/servers/<имя>#

/config/stream/upstreams/<upstream>/servers/<имя>#

HTTP-методы#

GET#

PUT#

DELETE#

PATCH#

`/status/angie`#

`/status/angie/license`#

`/status/connections`#

`/status/slabs/<зона>`#

`/status/resolvers/<зона>`#

`/status/http/server_zones/<зона>`#

`/status/http/location_zones/<зона>`#

`/status/http/metric_zones/<зона>`#

`/status/stream/server_zones/<зона>`#

`/status/stream/metric_zones/<зона>`#

`/status/http/caches/<cache>`#

`/status/http/acme_clients/<клиент>`#

`/status/http/limit_conns/<зона>`, `/status/stream/limit_conns/<зона>`#

`/status/http/limit_reqs/<зона>`#

`/status/http/upstreams/<upstream>`#

`health/probes`#

`queue`#

`/status/stream/upstreams/<upstream>`#

`/certificates/`#

Подразделы `/config`#

`/config/http/upstreams/<upstream>/servers/<имя>`#

`/config/stream/upstreams/<upstream>/servers/<имя>`#