OPNsense

Межсетевой экран и маршрутизатор с открытым исходным кодом: состояние каждого шлюза с временем прохождения сигнала и потерей пакетов, таблица состояний pf, счётчики и адреса интерфейсов, VPN-туннели, аренды DHCP, резолвер, службы, CARP и ожидающие обновления.

Проверено только на тестовом экземпляре

Эта интеграция была создана и проверена на OPNsense 26.1 (официальный образ, запущенный для этой цели в виртуальной машине) с ограниченным API-ключом, описанным ниже, а не на межсетевом экране, который годами обслуживает трафик домашней сети. Каждый вызов — это чтение, и каждая структура ответа взята с настоящего OPNsense, но у его шлюзов не было адреса мониторинга, он не входил в пару CARP и не использовал туннели OpenVPN или IPsec: эти части написаны по исходному коду OPNsense, а не по наблюдаемому ответу. Сообщите нам, если что-то сломается.

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

Помимо общих графиков, монитор OPNsense показывает три панели, построенные по тому, что сохранил опрос: открытие страницы никогда не обращается к самому межсетевому экрану.

• WAN и шлюзы — текущий публичный адрес каждого интерфейса, у которого есть шлюз, затем каждый шлюз с состоянием одним словом, временем прохождения сигнала и потерей пакетов. Недоступные шлюзы идут первыми. Ради этой панели и существует интеграция: на межсетевом экране с несколькими WAN резервный канал включается незаметно, и больше ничего в сети не меняется.
• Трафик и таблица состояний — сколько соединений отслеживает pf относительно настроенного предела, затем каждый интерфейс с состоянием канала, адресами, счётчиками байтов и пакетов, а также ошибками и отбросами, если они есть. Затем аренды DHCP, подсчитанные по серверам.
• Состояние межсетевого экрана — сначала остановленные службы, затем VPN-туннели с числом подключённых пиров, затем CARP, если межсетевой экран является половиной пары, затем прошивка (запущенная версия, что предлагает зеркало, ожидающие пакеты и нужна ли перезагрузка), затем резолвер, затем сама машина: время работы, нагрузка, память, подкачка, сетевые буферы, разделы и датчики температуры.

Только счётчики, никогда не трафик. DumbMonit не читает ни правил межсетевого экрана, ни состояний соединений, ни адресов клиентов, ни имён хостов. Аренды DHCP подсчитываются, но не перечисляются; VPN-сессии подсчитываются, но не называются по именам.

«none» означает «online»

GET /api/routes/gateway/status записывает "none" в поле status шлюза, когда всё в порядке — слово, которое само по себе читается как «нет информации». DumbMonit переводит его в online, чтобы страница, ряды данных и правила говорили то же самое, что и собственный интерфейс OPNsense. down и force_down — это сбои; loss и delay — предупреждения dpinger, при которых шлюз всё ещё отвечает.

Тот же вызов возвращает задержку, потери и стандартное отклонение в виде строк с единицей измерения ("8.4 ms", "0.0 %"), а также "~", если у шлюза нет адреса мониторинга. "~" даёт на один ряд меньше, а не ноль: шлюз, который никто не пингует, имеет не нулевую задержку в миллисекундах, а вообще никакой.

Проверка обновлений никогда не запускается

GET /api/core/firmware/status возвращает результат последней проверки межсетевого экрана — той, что показывает собственная панель OPNsense. DumbMonit никогда не отправляет форму POST этого вызова, как и /api/core/firmware/check, которая отправляла бы межсетевой экран к зеркалу при каждом измерении, с каждой установки DumbMonit.

Межсетевой экран, который ни разу не проверял обновления или только что установил обновление (что очищает кэш), отвечает "status": "none" — точно так же, как и актуальный. DumbMonit различает эти два случая и, пока проверка не выполнялась, публикует firmware_checked = 0 и ничего больше: ни «ноль ожидающих обновлений», ни «перезагрузка не требуется». Выполните проверку один раз в System → Firmware или дождитесь, пока она запустится по собственному расписанию межсетевого экрана.

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

Все метрики имеют префикс dumbmonit_opnsense_.

Семейство	Метрики	Метки
Идентификация	version_info (метки содержат версию OPNsense, версию FreeBSD и линейку продукта)
Машина	uptime_seconds, load1/5/15, cpu_count, memory_used/total_bytes, memory_used_percent (память включает кэш ZFS, который FreeBSD считает используемым), swap_used/total_bytes, swap_used_percent (отсутствует на машине без подкачки), mbuf_used и mbuf_total (кластеры сетевых буферов в использовании относительно kern.ipc.nmbclusters), mbuf_used_percent, mbuf_failures (отклонённые с момента загрузки выделения, счётчик)
Хранилище	disk_used_bytes, disk_total_bytes, disk_used_percent	device, mountpoint
Датчики	temperature_celsius	sensor
Шлюзы	gateway_up (0 только при down и force_down), gateway_monitored, gateway_delay_seconds, gateway_stddev_seconds, gateway_loss_percent, gateways_total, gateways_down	gateway, address
Интерфейсы	interface_up, interface_bytes_in/out, interface_packets_in/out, interface_errors_in/out, interface_drops, interface_collisions (счётчики, хранятся как есть), interface_address_info (адрес на данный момент, в метке)	interface, device, а для последней — ещё и address
Межсетевой экран	pf_states, pf_state_limit, pf_states_used_percent
DHCP	dhcp_leases, dhcp_leases_active	backend (kea, isc, dnsmasq)
VPN	vpn_tunnel_up, vpn_peers_total, vpn_peers_connected (WireGuard: рукопожатие в течение трёх минут), vpn_handshake_age_seconds (WireGuard, самый недавний пир; отсутствует, пока ни один пир не подключался), vpn_bytes_in/out, vpn_tunnels_down	kind (wireguard, openvpn, ipsec), tunnel (устройство WireGuard, wg0, либо описание IPsec и OpenVPN)
Резолвер	unbound_running, unbound_queries (счётчик), unbound_cache_hit_percent
Службы	service_running (1 или 0, один ряд на каждую службу из списка межсетевого экрана)	service
CARP	carp_enabled, carp_maintenance_mode, carp_vip_master (все отсутствуют на межсетевом экране, не входящем в пару)	interface, vhid, address
Прошивка	firmware_checked, затем — только после выполнения проверки — firmware_updates_pending, firmware_upgrade_available, firmware_reboot_required, firmware_connection_ok
Сбор	up, scrape_errors, scrape_duration_seconds

Счётчики интерфейсов хранятся как есть, как счётчики: оберните их в rate(), чтобы получить пропускную способность. При таком подходе перезагрузка межсетевого экрана выглядит как разрыв, а не как всплеск в несколько гигабайт в секунду.

gateway_up равно 1 для шлюза, который вообще не отслеживается, потому что нет оснований утверждать обратное; различает эти два случая gateway_monitored. У шлюза без адреса мониторинга нет ни ряда задержки, ни ряда потерь.

У межсетевого экрана, не входящего в пару высокой доступности, нет виртуального адреса CARP и вообще нет рядов CARP. Это межсетевой экран без кластера, а не деградировавший кластер: ни одно правило не может сработать.

WireGuard, OpenVPN, IPsec, Unbound и Kea — это плагины. Межсетевой экран, на котором плагина нет, отвечает 404, что не является ни ошибкой сбора, ни ошибкой аутентификации: одной метрикой меньше, и ничего в интерфейсе.

Применяемые встроенные правила: Monitor unreachable, Internet gateway down, Gateway losing packets, Gateway slow, Firewall state table filling up, Firewall network buffers exhausted, VPN tunnel down, Firewall resolver stopped, Firewall core service stopped, Firewall too hot, Firewall left in CARP maintenance mode, Firewall reboot pending, Firewall updates pending. Уведомления называют соответствующий шлюз, туннель, службу или датчик.

Что подготовить в OPNsense

Ниже приведены шаги из подсказки рядом с формой. Принцип: группа только с теми привилегиями статуса, которые нужны DumbMonit, пользователь, который никогда не входит в систему, и API-ключ, не принадлежащий ни одной из ваших собственных учётных записей. Именно эта группа была проверена на каждом вызове DumbMonit на OPNsense 26.1.

1. В веб-интерфейсе: System → Access → Groups → Add. Назовите группу так.

   dumbmonit
   

2. Отметьте в группе следующие привилегии точно так, как их называет OPNsense: Lobby: Dashboard (система, память, диски, температуры, таблица состояний), System: Gateways, Status: Interfaces, Status: Services, System: Firmware, Interfaces: Virtual IPs: Status (CARP) и Services: Unbound (MVC). Затем по одной на каждую используемую функцию: Services: DHCP: Kea(v4) или Services: Dnsmasq DNS/DHCP: Settings для аренд, VPN: WireGuard: Status, Status: OpenVPN, Status: IPsec. Пропущенная привилегия лишает ровно тех метрик, которые она обеспечивает, и ничего больше.

3. System → Access → Users → Add. Назовите учётную запись так, позвольте OPNsense сгенерировать случайный пароль (эта учётная запись никогда не входит в систему: она отвечает по своему ключу) и сделайте её членом группы dumbmonit.

   dumbmonit
   

4. Снова откройте этого пользователя для редактирования и в разделе API keys нажмите +. OPNsense скачает небольшой текстовый файл из двух строк, key= и secret=, и покажет секрет только один раз. Скопируйте ключ в поле API key в DumbMonit, а секрет — в поле API secret.

5. В DumbMonit введите адрес межсетевого экрана, например «192.168.1.1» или «fw.lan:8443». Межсетевой экран никогда не просят проверять обновления: DumbMonit читает результат проверки, которую OPNsense выполняет по своему расписанию или которую вы запускаете из System → Firmware.

Warning

Не используйте повторно учётную запись, под которой вы входите в систему: API-ключ — это пароль, срок действия которого никогда не истекает. У некоторых из перечисленных выше привилегий в OPNsense нет варианта только для чтения: Status: Services позволяет также запускать и останавливать службу, System: Firmware — также запускать обновление, а привилегии Unbound, Kea и Dnsmasq охватывают и их настройки. DumbMonit только читает, но чтобы ограничить возможности утёкшего ключа, ограничьте сети-источники группы адресом хоста DumbMonit. Никогда не выдавайте All pages. OPNsense также поставляется с самоподписанным сертификатом: если соединение отклоняется по этой причине, отметьте «Accept an unverifiable certificate» в параметрах.

Адрес: 192.168.1.1, fw.lan, fw.lan:8443, [fd00::1] или полный URL. Схема https и порт 443 добавляются, если не указаны.

Некоторые привилегии охватывают более одного вызова. Lobby: Dashboard включает эндпоинты системной информации, времени, памяти, диска, подкачки, сетевых буферов и температур, а также таблицу состояний; Status: Interfaces включает обзор интерфейсов со счётчиками и адресами. Пропущенная привилегия лишает ровно тех метрик, которые она обеспечивает: опрос по-прежнему успешен, а scrape_errors остаётся нулевым, потому что 403 на необязательном вызове трактуется как «эта учётная запись не вправе это видеть», а не как сбой. Обязательна только Lobby: Dashboard: без неё опрос не может даже прочитать имя и версию межсетевого экрана и сообщает об ошибке аутентификации.

camelCase или snake_case

OPNsense 25.7 переименовал пути API из systemResources в system_resources. Оба написания по-прежнему отвечают, но привилегии сравнивают путь буква в букву: на 25.7 и новее ограниченный ключ получает 403 на старом написании, а на 25.1 — на некоторых из новых. DumbMonit сначала запрашивает актуальное написание и при 403 переходит к другому, поэтому одна и та же группа работает по обе стороны переименования.

Параметры

Ключ	Название	По умолчанию	Подсказка
scheme	Протокол	https	HTTPS подходит для межсетевого экрана из коробки. HTTP — только если веб-интерфейс отдаётся открытым текстом.
port	Порт веб-интерфейса	443	Используется, если в адресе не указан порт.
insecure_tls	Принимать непроверяемый сертификат	false	По умолчанию OPNsense поставляется с самоподписанным сертификатом.
request_timeout_seconds	Тайм-аут на запрос (секунды)	15	Время, отведённое на каждый вызов API, от 1 до 120.
gateways	Следить за шлюзами	true	Читает, что dpinger сообщает о каждом шлюзе: доступен или нет, время прохождения сигнала и потерю пакетов.
interfaces	Следить за интерфейсами	true	Читает состояние канала каждого интерфейса, адреса и счётчики байтов, пакетов, ошибок и отбросов.
firewall	Следить за таблицей состояний	true	Читает, сколько соединений отслеживает pf и каков настроенный предел.
dhcp	Считать аренды DHCP	true	Считает аренды, которые выдаёт межсетевой экран, на каком бы сервере они ни работали. Только счётчики.
vpn	Следить за VPN-туннелями	true	Читает WireGuard, OpenVPN и IPsec: какие туннели существуют и какие из них подняты.
unbound	Следить за резолвером	true	Читает, отвечает ли Unbound.
services	Следить за службами	true	Читает список служб, которыми управляет межсетевой экран, и какие из них запущены.
carp	Следить за CARP	true	Читает виртуальные адреса пары высокой доступности и постоянный режим обслуживания.
firmware	Следить за обновлениями	true	Читает результат последней проверки обновлений межсетевого экрана и ожидается ли перезагрузка.
temperature	Читать датчики температуры	true	Читает датчики процессора и платы, которые предоставляет межсетевой экран.

Частые ошибки

Симптом	Вероятная причина
Ошибка аутентификации	Ключ и секрет перепутаны, или ключ был удалён у пользователя. OPNsense показывает секрет только один раз: если он утерян, создайте другой ключ и удалите старый.
Веб-страница вместо JSON	API-ключ отклонён, или учётная запись не имеет доступа к этому эндпоинту. Тогда OPNsense отдаёт свою страницу входа с кодом 200; DumbMonit сообщает об этом как о проблеме аутентификации, а не как о нечитаемом ответе.
Ошибка сертификата	Самоподписанный сертификат: установите доверенный (ACME — это плагин) или включите insecure_tls.
Совсем нет метрик шлюзов	Параметр gateways выключен, или в группе нет System: Gateways. У межсетевого экрана без заданных шлюзов их действительно нет.
У шлюза нет задержки или потерь	У него нет адреса мониторинга, поэтому dpinger его не пингует. OPNsense записывает ~, а DumbMonit не публикует ряд вместо нуля.
«Gateway down» срабатывает для работающего канала	Адрес мониторинга недоступен, хотя канал поднят — частый случай у провайдера, отбрасывающего ICMP. Задайте другой адрес мониторинга в System → Gateways.
Нет метрик таблицы состояний	В группе нет Lobby: Dashboard.
Ошибка аутентификации на ключе, который работает в браузерном инструменте	Инструмент использовал другое написание пути. С ограниченным ключом OPNsense 25.7 и новее отвечает 403 на systemInformation и 200 на system_information.
Нет метрик обновлений, кроме firmware_checked	Межсетевой экран ни разу не проверял обновления или только что установил одно. Выполните проверку в System → Firmware.
Нет метрик VPN	Плагин не установлен или ни один туннель не настроен. Отключённое подключение IPsec намеренно не сообщается как недоступное.
«Firewall resolver stopped» на межсетевом экране, который прекрасно резолвит	Unbound установлен, но выключен, потому что межсетевой экран резолвит чем-то другим. Отключите это правило.
Версия прошивки выглядит устаревшей	Межсетевой экран давно не проверял зеркало. DumbMonit читает последнюю проверку и никогда не запускает её.
scrape_errors больше нуля	Один необязательный вызов завершился ошибкой по причине, отличной от отсутствия привилегии или плагина, — обычно тайм-аут. Остальные метрики не затронуты.