UniFi Network

Сеть UniFi и то, чем она управляет: шлюзы, коммутаторы и точки доступа, которые отключены, изолированы или ждут принятия, ожидающие обновления прошивки, WAN-каналы и подключение к Интернету, как их видит шлюз, число клиентов и тревоги, поднятые UniFi. Работает с приложением UniFi Network консоли UniFi OS (Dream Machine, Cloud Gateway, Cloud Key) и с самостоятельно размещённым UniFi Network Server.

DumbMonit читает UniFi по API-ключу или под локальной учётной записью с ролью View Only. Он никогда не перезапускает, не принимает, не обновляет и не конфигурирует устройство.

Сбой, за которым стоит следить: точка доступа или коммутатор тихо отваливается. Клиенты переходят на соседнюю точку доступа, сеть продолжает работать, а дыра в покрытии или потерянный аплинк обнаруживаются лишь спустя дни. То же относится ко второму WAN-каналу, который отключился: ничто не ломается, пока не откажет и первый.

Два способа входа

Учётные данные	Используемый API	Что читает
API-ключ (консоль UniFi OS)	Официальный Integration API, по адресу `/proxy/network/integration/v1` на консоли и `/integration/v1` на самостоятельно размещённом сервере	Версия, устройства и их состояние, обновления прошивки, нагрузка, память и время работы каждого онлайн-устройства, число клиентов
Учётная запись View Only	Классический API (`/api/s/<site>/stat/*`), по адресу `/proxy/network/api/…` на консоли	Всё перечисленное, а также клиенты по устройствам и типам, WAN-каналы, состояние WAN и Интернета и тревоги

Состояние WAN, Интернета и тревоги существуют только в классическом API. С ключом DumbMonit также запрашивает у классического API состояние WAN и Интернета с тем же ключом; если контроллер отказывает, эти ряды просто отсутствуют, без ошибки.

Тревоги — это записи «критического» системного журнала UniFi за последние 24 часа (UniFi Network 8 и новее) либо неархивированные тревоги в более старых версиях. Это единственный POST, который отправляет DumbMonit, и он только читает.

Сессия, открытая под учётной записью View Only, сохраняется от одного опроса до другого и открывается заново по истечении: UniFi не фиксирует новый вход каждую минуту.

За чем он следит

Все метрики имеют префикс dumbmonit_unifi_. Ряды устройств несут device (его имя или MAC-адрес, если имени нет), mac, model и type (gateway, switch, access_point, other).

Метрика	Что	Метки
`info`	значение 1	`version`, `api` (`integration` или `classic`)
`devices`	устройства по состоянию: `online`, `offline`, `pending`, `updating`, `adopting`, `adoption_failed`, `isolated`, `other`	`state`
`devices_upgradable`	принятые устройства с доступным обновлением прошивки
`device_state`	0 онлайн, 1 офлайн, 2 ожидает принятия, 3 обновляется или конфигурируется, 4 принимается, 5 сбой принятия, 6 изолировано, 7 другое	метки устройства
`device_up`	1 онлайн или обновляется, 0 офлайн, изолировано или не удалось принять; отсутствует для устройства, ещё не принятого	метки устройства
`device_upgradable`	1, когда доступно обновление прошивки	метки устройства, `firmware`
`device_uptime_seconds`, `device_cpu_percent`, `device_memory_percent`	только онлайн-устройства	метки устройства
`device_clients`	клиенты, подключённые к устройству (учётная запись View Only)	метки устройства
`wan_link_up`	1, когда WAN-порт шлюза поднят; у отключённого порта рядов нет	метки устройства, `wan` (`wan1`, `wan2`)
`wan_up`, `internet_up`	состояние WAN и Интернета шлюза; отсутствует без шлюза UniFi
`internet_latency_seconds`	задержка, измеренная шлюзом
`wan_availability_percent`	доступность каждого WAN за последние 24 часа	`wan`
`subsystem_status`	0 ok, 1 предупреждение, 2 ошибка, 3 неизвестно, для `wlan`, `wan`, `www`, `lan`, `vpn`	`subsystem`
`clients`	клиенты на площадке
`clients_by_type`	`wireless`, `wired`, `guest`, `vpn` (учётная запись View Only)	`type`
`alarms`	записи критического системного журнала за последние 24 часа или неархивированные тревоги
`scrape_errors`	вызовы, завершившиеся ошибкой при последнем опросе
`port_enabled`, `port_up`, `port_speed_bps`, `port_full_duplex`, `port_uplink`	порты каждого доступного коммутатора или шлюза (учётная запись только для чтения, `port_table`); у отключённого порта `port_up` нет	`device`, `mac`, `port` (номер на передней панели), `port_name`
`port_poe_enabled`, `port_poe_watts`	PoE каждого порта	те же
`port_rx_bytes_total`, `port_tx_bytes_total`, `port_rx_errors_total`, `port_tx_errors_total`	счётчики по портам, их рисует панель коммутатора	те же
`port_neighbor_info`	значение 1, LLDP-сосед порта (`lldp_table`)	те же, `remote_chassis`, `remote_port`

Применяемые встроенные правила: UniFi device offline, UniFi Internet down, UniFi WAN link down, UniFi gateway CPU high, UniFi device waiting for adoption, UniFi firmware update available, UniFi alarms, а также Monitor unreachable.

Устройства

/rest/user (классический API, читается с любыми учётными данными) перечисляет всех клиентов, которых когда-либо видел контроллер, — на практике это большая часть домашней сети: проходящие мимо телефоны, гостевой Wi-Fi, умные устройства, которые никогда не возвращаются. Отслеживание устаревания всех их похоронило бы тревогу под устройствами, которые просто никогда не возвращаются, а не под теми, что замолчали. По умолчанию учитываются только клиенты, которых пользователь так или иначе отметил: названные в UniFi, зарезервированные на фиксированный IP или с заметкой. Параметр Clients to watch besides the marked ones добавляет конкретные MAC-адреса или имена клиентов либо all, чтобы отслеживать всех клиентов (не рекомендуется нигде, кроме небольшой, преимущественно статичной сети).

Отслеживаемые клиенты публикуются в общем семействе, которое используют все интеграции DumbMonit, отслеживающие клиентские устройства, — dumbmonit_client_device_*, с префиксом без unifi, полностью описанном в разделе Client devices:

Метрика	Что	Метки
`last_seen_timestamp_seconds`	Последнее подключение, как его сообщает `/rest/user`	`device`, `type` (`Wired`, `Wireless` или `Unknown`), `os` (пусто), `user` (пусто), `kind`
`stale_seconds`	Положительна, когда отслеживаемый клиент превысил `device_stale_days` (по умолчанию 3) без подключения; запускает правило Client device stale	`device`, `type`, `os`, `user`, `kind`, `signal` (всегда `connection`: у UniFi нет резервных копий, о которых можно сообщать)

Страница монитора

Панель над графиками читает то, что сохранил опрос; открытие страницы никогда не обращается к UniFi. Сначала она говорит, что не так (отключённые устройства, Интернет или WAN-канал недоступны, тревоги), затем показывает устройства по типам с их состоянием, прошивкой и нагрузкой, и клиентов, затем таблицу отслеживаемых клиентов с их последним подключением.

Как это проверялось

Вход, роль View Only, ответы об ошибках (отклонённый пароль, неизвестная площадка, отклонённый ключ, истёкшая сессия) и ответы контроллера без устройств проверялись на UniFi Network 10.6.106, самостоятельно размещённом. Принять там ни одно устройство не удалось: список устройств, состояние оснащённой площадки, известные клиенты (/rest/user) и данные Integration API проверены по официальной документации.

Создайте доступ только для чтения в UniFi Network

На консоли UniFi OS (Dream Machine, Cloud Gateway, Cloud Key) можно создать API-ключ: в UniFi Network, Settings → Control Plane → Integrations → Create API Key. Назовите его в честь DumbMonit и скопируйте сейчас: он показывается только один раз. Ключ читает устройства, их нагрузку и число клиентов через официальный Integration API.
Для состояния WAN, Интернета и тревог, а также на самостоятельно размещённом UniFi Network Server используйте вместо этого локальную учётную запись с ролью View Only: Settings → Admins & Users → Create New. Назовите её так, задайте длинный случайный пароль, ограничьте её локальным доступом и установите её роль в UniFi Network как View Only. View Only читает всё и не может ничего изменить.
```
dumbmonit
```
В DumbMonit введите адрес консоли или сервера, например «unifi.lan» (порт 443 на консоли) или «unifi.lan:8443» для самостоятельно размещённого сервера, и вставьте ключ или учётную запись. Если сеть — не площадка по умолчанию, задайте в параметре Site короткое имя, показанное в адресной строке после /manage/ или /network/.
DumbMonit только читает. Он никогда не перезапускает, не принимает, не обновляет и не конфигурирует устройство и никогда не подтверждает тревогу.

Не используйте учётную запись владельца или облачную учётную запись UI.com: утёкший пароль открыл бы все связанные с ней консоли. Держите двухфакторную аутентификацию выключенной только для этой локальной учётной записи View Only, так как сервер мониторинга не может ввести код. Консоли по умолчанию используют самоподписанный сертификат: включите «Accept an unverifiable certificate», если вы не установили собственный. UniFi знает каждого клиента, когда-либо подключавшегося, в большинстве своём это проходящие мимо телефоны: по умолчанию на устаревание проверяются только те, что названы, зарезервированы на фиксированный IP или имеют заметку в UniFi, чтобы не получать тревогу на телефон каждого гостя. Перечислите больше в параметре Clients to watch или введите all.

Контроллер ещё не настроен

Самостоятельно размещённый контроллер, мастер первоначальной настройки которого не завершён, отвечает на каждый запрос перенаправлением на /setup. Тогда DumbMonit сообщает «The UniFi controller is not set up yet» как ошибку конфигурации (а не отклонённый пароль): завершите мастер в браузере, затем опросите снова.

Учётные данные

Учётные данные	Поля
API-ключ (консоль UniFi OS)	Ключ, созданный в Settings → Control Plane → Integrations, отправляется как `X-API-KEY`.
Учётная запись View Only	Имя пользователя и пароль локальной учётной записи View Only.

Адрес: имя хоста или IP (unifi.lan), host:port (unifi.lan:8443 для самостоятельно размещённого сервера) или полный URL; адрес, скопированный из браузера, с /manage/… или /network/…, принимается. Параметры: площадка (default), порт (443), проверка сертификата, тайм-аут запроса (15 с), клиенты для отслеживания помимо отмеченных (пусто или all) и устаревание устройства (device_stale_days, по умолчанию 3 дня).