HTTP API

vminfo --web запускает легковесные HTTP API и дашборд только для чтения.

Запуск сервера

vminfo --web

Адрес по умолчанию:

http://127.0.0.1:20021

Произвольный адрес:

vminfo --web --bind 0.0.0.0 --port 8080 --interval 1s

Авторизация

По умолчанию дашборд и API доступны локально и без авторизации.

При включённом --token:

vminfo --web --token
vminfo --web --token my-secret

• пустой --token автоматически генерирует URL-безопасный токен
• --token my-secret использует фиксированный токен
• при первом успешном заходе через /?token=... устанавливается cookie для последующих запросов
• /healthz остаётся открытым
• /, /api/v1/* и /ws требуют токен или cookie авторизации
• режим с защитой токеном не открывает разрешающий Access-Control-Allow-Origin: *
• запросы WebSocket должны использовать тот же origin браузера, что и хост дашборда

Эндпоинты

GET /healthz

Открытая проверка здоровья веб-процесса.

{
  "status": "ok",
  "ws_clients": 0
}

GET /api/v1/snapshot

Возвращает текущий полный снимок дашборда.

{
  "timestamp": "2026-06-14T12:00:00Z",
  "system": {},
  "cpu": {},
  "memory": {},
  "disk": {},
  "network": {},
  "load": {},
  "processes": {},
  "health": {}
}

GET /api/v1/cpu

Возвращает итоги по CPU, загрузку по ядрам и краткую историю CPU в памяти.

GET /api/v1/memory

Возвращает итоги, использование, доступность и проценты для памяти и swap.

GET /api/v1/disk

Возвращает использование файловой системы и скорости дискового ввода-вывода.

GET /api/v1/network

Возвращает пропускную способность сети, количество соединений TCP/UDP и счётчики интерфейсов.

На Linux тело ответа также включает распределение состояний TCP (сколько сокетов находится в ESTABLISHED, TIME_WAIT, SYN_RECV, …) и использование conntrack (текущее относительно максимума записей nf_conntrack), чтобы можно было заметить насыщение сокетов или таблицы отслеживания соединений.

GET /api/v1/processes

Возвращает дополненный список процессов.

Поддерживаемые параметры запроса:

Параметр	Описание
filter	Регистронезависимое совпадение по PID, PPID, имени, команде, пользователю или состоянию
q	Псевдоним для filter
sort	cpu, mem, pid или name; по умолчанию cpu
limit	Максимальное число возвращаемых строк; 0 или отсутствие означают без ограничения

Пример:

curl 'http://127.0.0.1:20021/api/v1/processes?filter=ssh&sort=mem&limit=10'

Структура ответа:

{
  "total": 128,
  "list": [
    {
      "pid": 1234,
      "ppid": 1,
      "name": "sshd",
      "user": "root",
      "cpu_percent": 0.1,
      "mem_percent": 0.2,
      "rss": 12345678,
      "status": "S",
      "command": "sshd: user@pts/0",
      "threads": 1,
      "nice": 0,
      "uptime": 3600,
      "started_at_unix": 1781434800
    }
  ]
}

GET /api/v1/system

Возвращает метаданные хоста, ОС/ядро/архитектуру, модель CPU/число ядер и uptime.

GET /api/v1/health

Возвращает легковесную оценку здоровья и предупреждения, используемые дашбордом.

{
  "score": 90,
  "warnings": [
    {
      "level": "warning",
      "code": "disk_high",
      "message": "disk usage is 88.5%"
    }
  ]
}

Поле code идентифицирует предупреждение. Сетевые коды включают:

Код	Значение
network_errors	Устойчивый уровень ошибок на интерфейс (событий/с, не накопительные счётчики)
network_drops	Устойчивый уровень потерь пакетов на интерфейс
tcpconn_high	Необычно высокое число сокетов TCP (≥5000 предупреждение / ≥20000 критично)
conntrack_high	Таблица conntrack заполняется (≥85% предупреждение / ≥95% критично, Linux)

Решение о network_errors / network_drops принимается по скоростям, а не по сырым счётчикам, поэтому долго живущий накопленный итог не удерживает в остальном здоровый хост в отмеченном состоянии.

POST /api/v1/net/diag

Запускает сетевую диагностику по требованию — те же пробы, что и команда net, вызываемая из дашборда. Она смонтирована на защищённом муксе, поэтому при включённой авторизации по токену наследует проверки токена/cookie и same-origin так же, как остальные маршруты /api/v1/*.

Тело запроса:

Поле	Описание
action	dns, port, ping или ip
target	Домен (dns) или хост (port/ping); обязательно. Для ip — IP для поиска, или пусто для собственного публичного IP
port	Целевой порт (действия port / ping)
server	Необязательный DNS-сервер (dns) или базовый URL сервиса поиска IP (ip)
timeout_ms	Таймаут на пробу в миллисекундах (port / ping)
count	Число проб (ping)
mode	Режим ping: tcp (по умолчанию) или icmp

Пример:

curl -X POST http://127.0.0.1:20021/api/v1/net/diag \
  -H 'Content-Type: application/json' \
  -d '{"action":"ping","target":"example.com","port":443,"count":4,"mode":"tcp"}'

Структура ответа соответствует JSON-результату соответствующей команды CLI (DNSResult, PortResult, PingResult или IPInfo).

GET /ws

Поток WebSocket с полными снимками дашборда.

• отправляет последний снимок сразу после подключения
• стримит обновлённые снимки по мере обновлений сборщика
• в режиме с защитой токеном запрос должен пройти авторизацию и проверки same-origin

См. также

• Руководство по веб-дашборду
• Справочник команд