API awg‑manager

Полная справка по REST API awg‑manager. Описаны все эндпоинты, аутентификация, форматы запросов и ответов. Для общего знакомства смотрите Быстрый старт, а примеры использования конкретных функций — Руководство.

Общие сведения

• Базовый URL: http://<router-ip>:<port>/api (порт по умолчанию 2222, выбирается динамически)
• Аутентификация: сессионная cookie awg_session. Большинство эндпоинтов требуют валидной сессии. Публичные (без аутентификации):
  /auth/login, /auth/logout, /auth/status, /health, /hook/ndms, /dns-check/probe, /boot-status
• Формат ответа (успех):

  { "success": true, "data": { ... } }
• Формат ответа (ошибка):

  { "success": false, "error": "сообщение", "code": "ERROR_CODE" }
• Коды ошибок (неполный список):
  • METHOD_NOT_ALLOWED — неверный HTTP метод
  • MISSING_NAME, MISSING_ID, MISSING_MAC и т.п.
  • INVALID_NAME, INVALID_ID, INVALID_JSON
  • NOT_FOUND — ресурс не найден
  • UNAUTHORIZED — требуется аутентификация
  • AUTH_FAILED — неверные учётные данные
  • ROUTER_UNAVAILABLE — нет связи с роутером
  • CREATE_FAILED, UPDATE_FAILED, DELETE_FAILED, LIST_FAILED
  • INTERNAL_ERROR — внутренняя ошибка сервера

Аутентификация

POST /auth/login

Тело:

{ "login": "admin", "password": "secret" }

Успех (200): { "success": true, "login": "admin" }
Ошибки:

• AUTH_FAILED (401) – неверный логин/пароль
• ROUTER_UNAVAILABLE (503) – роутер недоступен

GET /auth/status

Успех (200):
Если аутентификация включена и сессия валидна:

{ "authenticated": true, "login": "admin", "expiresIn": 3540 }

Если сессии нет:

{ "authenticated": false }

Если аутентификация отключена глобально (в настройках):

{ "authenticated": true, "authDisabled": true }

POST /auth/logout

Успех (200): { "success": true }

Health и boot

GET /health

{ "success": true, "data": { "ok": true, "version": "2.8.0" } }

GET /boot-status

{
  "initializing": false,
  "remainingSeconds": 0,
  "phase": "ready",
  "instanceId": "a1b2c3..."
}

Система

GET /system/info

Возвращает объект (пример):

{
  "version": "2.8.0",
  "goVersion": "go1.22.0",
  "goArch": "arm",
  "keeneticOS": "KeeneticOS 5.0",
  "isOS5": true,
  "firmwareVersion": "5.0.1",
  "supportsExtendedASC": true,
  "supportsHRanges": true,
  "supportsPingCheck": true,
  "totalMemoryMB": 1024,
  "isLowMemory": false,
  "gcMemLimit": "512MiB",
  "gogc": "100",
  "disableMemorySaving": false,
  "kernelModuleExists": true,
  "kernelModuleLoaded": true,
  "kernelModuleModel": "MT7621",
  "kernelModuleVersion": "1.0",
  "isAarch64": false,
  "activeBackend": "kernel",
  "routerIP": "192.168.1.1",
  "bootInProgress": false,
  "backendAvailability": {
    "nativewg": true,
    "kernel": true
  },
  "singbox": {
    "installed": true,
    "version": "v1.8.0"
  }
}

GET /system/wan-interfaces

[
  { "name": "ppp0", "label": "PPPoE", "state": "up" },
  { "name": "eth3", "label": "WAN", "state": "down" }
]

GET /system/all-interfaces

Массив интерфейсов с полями name, label, type и т.д. (зависит от NDMS).

POST /system/hydraroute-control

Тело: { "action": "start" | "stop" | "restart" }
Ответ: статус после выполнения (как в GET /system/hydraroute-status).

Настройки приложения

Пример ответа GET /settings/get:

{
  "port": 2222,
  "authEnabled": true,
  "sessionTTLSeconds": 3600,
  "disableMemorySaving": false,
  "serverInterfaces": ["Wireguard0"],
  "hiddenSystemTunnels": ["Wireguard2"],
  "managedServer": { ... }
}

При обновлении передаётся аналогичный объект.

Обновления

GET /system/update/changelog

Параметры:

• from (опционально) – версия, начиная с которой показывать изменения
• to (обязательно) – целевая версия

Если from не указан, возвращается запись для версии to.
Ответ: { "entries": [ { "version": "2.8.0", "changes": [...] } ] }

NDMS save‑status

Ответ:

{
  "state": "idle",      // idle, pending, saving, error, failed
  "lastError": "",
  "lastSaveAt": "2025-01-01T12:00:00Z",
  "pendingCount": 0
}

VPN‑серверы (WireGuard Server Interfaces)

Примечание: Имя должно соответствовать шаблону WireguardN (N – число).
POST/DELETE /servers/mark возвращают свежий ServersSnapshot (как /servers/all).
Структура /servers/all:

{
  "servers": [...],
  "managed": { ... },        // если создан managed‑сервер
  "managedStats": { ... },   // статистика пиров managed
  "wanIP": "123.45.67.89"
}

Управляемый WireGuard‑сервер

Пример создания:

{
  "address": "10.10.0.1",
  "mask": "24",
  "listenPort": 51820,
  "interfaceName": "Wireguard5"   // опционально
}

ASC‑параметры (ответ):

{
  "i1": 0, "i2": 0, "i3": 0, "i4": 0, "i5": 0,
  "jc": 0, "jmin": 0, "jmax": 0,
  "s1": 0, "s2": 0, "s3": 0, "s4": 0,
  "h1": 0, "h2": 0, "h3": 0, "h4": 0
}

Туннели (управляемые)

GET /tunnels/list – ответ

[
  {
    "id": "my-tunnel",
    "name": "My Tunnel",
    "type": "awg",
    "status": "running",
    "enabled": true,
    "defaultRoute": false,
    "ispInterface": "ppp0",
    "ispInterfaceLabel": "PPPoE",
    "resolvedIspInterface": "ppp0",
    "resolvedIspInterfaceLabel": "PPPoE",
    "endpoint": "1.2.3.4:51820",
    "address": "10.0.0.2/24",
    "interfaceName": "awg0",
    "ndmsName": "Wireguard3",
    "hasAddressConflict": false,
    "rxBytes": 1234567,
    "txBytes": 9876543,
    "lastHandshake": "2025-01-01T12:00:00Z",
    "backend": "kernel",
    "backendType": "AmneziaWG",
    "awgVersion": "amneziawg",
    "mtu": 1420,
    "startedAt": "2025-01-01T11:00:00Z",
    "pingCheck": { "status": "alive", "enabled": true, "method": "icmp" }
  }
]

GET /tunnels/all – ответ

{
  "tunnels": [ ... ],   // те же элементы, что в /tunnels/list
  "external": [ ... ],  // внешние туннели (см. раздел "Внешние туннели")
  "system": [ ... ]     // системные туннели (см. раздел "Системные туннели")
}

POST /tunnels/create

Тело – объект AWGTunnel (минимально: name, interface, peer). ID генерируется автоматически. Ответ: созданный туннель (как в GET /tunnels/get).

POST /tunnels/update?id=

Тело – частичное обновление (только изменяемые поля).
Ответ: обновлённый туннель + поле warnings (при конфликтах адресов).

POST /tunnels/replace?id=

{ "content": "новый конфиг", "name": "новое имя" }

Если туннель запущен, он будет остановлен перед заменой и перезапущен.

Управление туннелями (Start/Stop)

Все эндпоинты возвращают обновлённый туннель (как в GET /tunnels/get?id=).

Статус туннелей

Отличаются облегчённой структурой (только статус, счётчики). Используются внутри orchestrator.

Ping‑check мониторинг

Конфигурация ping‑check (тело POST):

{
  "host": "8.8.8.8",
  "mode": "icmp",          // icmp, connect, tls
  "updateInterval": 45,
  "maxFails": 3,
  "minSuccess": 1,
  "timeout": 5,
  "restart": true,
  "port": 0
}

GET /pingcheck/status ответ:

{
  "enabled": true,
  "tunnels": [
    {
      "tunnelId": "my-tunnel",
      "tunnelName": "My Tunnel",
      "enabled": true,
      "status": "alive",
      "method": "icmp",
      "lastCheck": "2025-01-01T12:00:00Z",
      "failCount": 0
    }
  ]
}

Внешние туннели (неуправляемые)

GET /external-tunnels ответ:

[
  {
    "interfaceName": "opkgtun5",
    "tunnelNumber": 5,
    "isAWG": true,
    "publicKey": "...",
    "endpoint": "1.2.3.4:51820",
    "lastHandshake": "2025-01-01T12:00:00Z",
    "rxBytes": 123,
    "txBytes": 456
  }
]

POST /external-tunnels/adopt?interface=opkgtun5
Тело: { "content": "полный конфиг", "name": "желаемое имя" }
Ответ: созданный туннель (аналогично /tunnels/get?id=).

Системные туннели (нативные Keenetic)

Примечание: Имя должно быть WireguardN.

Политики доступа (Access Policies) – только OS5

Параметр ?refresh=true для GET /access-policies и GET /access-policies/devices – принудительно сбрасывает кэш NDMS.

Пример создания политики:

{ "description": "My Policy" }

Ответ: { "name": "Policy0" }.

Пример назначения устройства:

{ "mac": "AA:BB:CC:DD:EE:FF", "policy": "Policy0" }

Пример разрешения интерфейса:

{ "name": "Policy0", "interface": "Wireguard0", "order": 0 }

Поднять/опустить интерфейс:

{ "name": "Wireguard0", "up": true }

DNS‑маршруты

Структура DNS‑маршрута:

{
  "id": "dns-1",
  "name": "My Domains",
  "domains": ["example.com", "domain.org"],
  "enabled": true,
  "backend": "ndms",       // ndms, hydraroute или static
  "subscriptionURL": "",
  "lastUpdate": ""
}

Пример создания:

{
  "name": "My Domains",
  "domains": ["example.com"],
  "backend": "ndms"
}

Bulk backend:

{ "listIDs": ["id1","id2"], "backend": "hydraroute" }

Статические маршруты

Структура:

{
  "id": "static-1",
  "name": "Route List",
  "subnets": ["192.168.2.0/24", "10.0.0.0/16"],
  "enabled": true,
  "tunnelID": "my-tunnel"
}

Импорт:

{
  "tunnelID": "my-tunnel",
  "name": "Imported Routes",
  "content": "route add ...\nroute add ..."
}

Клиентские маршруты

Структура:

{
  "id": "cr-1",
  "clientIP": "192.168.1.100",
  "tunnelID": "my-tunnel",
  "enabled": true
}

WAN статус

Ответ:

{
  "interfaces": {
    "ppp0": { "up": true, "label": "PPPoE" },
    "eth3": { "up": false, "label": "WAN" }
  },
  "anyWANUp": true
}

Соединения (conntrack)

Параметры:

• tunnel – имя туннеля (интерфейс)
• protocol – tcp/udp/icmp
• search – поиск по IP или порту
• sortBy – поле сортировки (например, rxBytes)
• sortDir – asc или desc
• offset – сдвиг (постранично)
• limit – количество записей на страницу (максимум 1000, иначе обрезается)

Ответ:

{
  "total": 42,
  "connections": [
    {
      "srcIP": "192.168.1.100",
      "srcPort": 12345,
      "dstIP": "8.8.8.8",
      "dstPort": 443,
      "protocol": "tcp",
      "state": "ESTABLISHED",
      "tunnel": "awg0",
      "rxBytes": 1024,
      "txBytes": 2048
    }
  ]
}

Диагностика

Параметры /diagnostics/stream:

• mode=quick|full (по умолчанию quick)
• restart=true – перезапускать ли sing‑box при измерении
• route=direct|tunnel – режим маршрутизации для тестов
• tunnelId=xxx – ID туннеля при route=tunnel

Логи приложения

Параметры GET:

• group – группа (tunnel, system, routing)
• subgroup – подгруппа (lifecycle, settings, dnsroute …)
• level – info, warn, error, debug
• limit – количество (default 200)
• offset – сдвиг

Ответ:

{
  "enabled": true,
  "logs": [
    { "timestamp": "2025-01-01T12:00:00Z", "level": "info", "group": "tunnel", "subgroup": "lifecycle", "message": "Tunnel started" }
  ],
  "total": 1500
}

Тестирование туннелей

Пример ответа /test/ip:

{ "ip": "1.2.3.4", "service": "ipv4.icanhazip.com" }

Пример ответа /test/connectivity:

{ "connected": true, "latency": 42, "reason": "" }

HydraRoute Neo

Sing‑box

Добавление туннелей:

{ "links": "vless://...\nhy2://...\ntrojan://..." }

Ответ: { "imported": [...], "errors": [...], "tunnels": [...] }

GET /singbox/tunnels ответ (enriched):

[
  {
    "tag": "my-tunnel",
    "type": "vless",
    "server": "example.com",
    "port": 443,
    "connectivity": { "connected": true, "latency": 120 }
  }
]

Clash API проксирует все эндпоинты (например, /proxies, /connections, /traffic, /logs, /configs).

Device Proxy (SOCKS5/HTTP)

PUT /proxy/config тело:

{
  "enabled": true,
  "port": 1080,
  "listenAll": true,
  "selectedOutbound": "direct",
  "auth": { "enabled": false, "username": "", "password": "" }
}

POST /proxy/runtime/select:

{ "tag": "my-tunnel" }

Захват сигнатуры

Используется для обхода прозрачного прокси (AmneziaWG).
Ответ: { "signature": "..." }

Терминал (ttyd)

Статус:

{ "installed": true, "running": true, "sessionActive": false }

Пример ответа:

{ "success": false, "error": "Terminal already open in another tab", "code": "SESSION_ACTIVE" }

WebSocket требует подпротокола tty. При активной сессии другие подключения отклоняются (409 Confict).

Server‑Sent Events (SSE)

Endpoint: GET /events (требует аутентификации)
Content-Type: text/event-stream

События публикуются в реальном времени. Клиент должен перезапрашивать холодные данные по resource:invalidated.

Типы событий и данные:

Пример потока:

event: connected
data: {"ok":true}

event: resource:invalidated
data: {"resource":"tunnels","reason":"list-changed"}

event: tunnel:state
data: {"id":"my-tunnel","state":"running","backend":"kernel"}

Унифицированные маршрутизационные ресурсы (polling aliases)

Эти эндпоинты используются фронтендом для опроса (polling) и повторяют данные из соответствующих разделов.

POST /routing/refresh возвращает { "missing": [...] } (список отсутствующих целей).

Прочие эндпоинты

POST /hook/ndms принимает form-urlencoded с полями: type, id, system_name, layer, level, address, up, connected. Используется скриптами NDMS.

Основные коды ошибок

METHOD_NOT_ALLOWED, UNAUTHORIZED, BAD_REQUEST, NOT_FOUND, INVALID_JSON, MISSING_NAME, MISSING_ID, MISSING_MAC, INVALID_NAME, INVALID_ID, INVALID_ENDPOINT, CREATE_FAILED, UPDATE_FAILED, DELETE_FAILED, LIST_FAILED, AUTH_FAILED, ROUTER_UNAVAILABLE, INTERNAL_ERROR, CONFLICT, SERVICE_UNAVAILABLE, NO_STREAMING, PINGCHECK_CONFIGURE_ERROR, PINGCHECK_REMOVE_ERROR, HYDRAROUTE_CONTROL_ERROR, GET_ASC_FAILED, SET_ASC_FAILED, STATIC_ROUTE_IMPORT_ERROR, NOT_RUNNING, SESSION_ACTIVE

Документация составлена по исходному коду awg‑manager (файлы server.go, api/.go, internal/…). Актуальна для версии ≥2.8.0.*

Что дальше?

• Быстрый старт — создайте первый туннель и протестируйте через API
• Руководство — детальные инструкции по всем функциям
• Решение проблем — диагностика ошибок и восстановление