UniFi Network
Le réseau UniFi et ce qu’il gère : passerelles, commutateurs et points d’accès hors ligne, isolés ou en attente d’adoption, mises à jour de firmware en attente, les liens WAN et la connexion Internet telle que la passerelle les voit, le nombre de clients, et les alarmes qu’UniFi a levées. Ça fonctionne avec l’application UniFi Network d’une console UniFi OS (Dream Machine, Cloud Gateway, Cloud Key) et avec un UniFi Network Server auto-hébergé.
DumbMonit lit UniFi avec une clé d’API ou avec un compte local portant le rôle View Only. Il ne redémarre, n’adopte, ne met à jour ni ne provisionne jamais un appareil.
La panne à surveiller : un point d’accès ou un commutateur qui se déconnecte discrètement. Les clients basculent vers le point d’accès suivant, le réseau continue de fonctionner, et le trou de couverture ou le lien montant perdu n’est remarqué que des jours plus tard. Pareil pour un second lien WAN qui est tombé : rien ne casse jusqu’à ce que le premier tombe aussi.
Ports réseau à ouvrir
Section intitulée « Ports réseau à ouvrir »Du serveur DumbMonit (ou de son agent relais) vers l’équipement :
| Port | Protocole | Usage |
|---|---|---|
| 443 | TCP | API (HTTPS, par défaut) |
| 8443 | TCP | Seulement avec un UniFi Network Server auto-hébergé |
Deux façons d’entrer
Section intitulée « Deux façons d’entrer »| Identifiant | API utilisée | Ce qu’elle lit |
|---|---|---|
| Clé d’API (console UniFi OS) | L’Integration API officielle, sur /proxy/network/integration/v1 sur une console et /integration/v1 sur un serveur auto-hébergé | Version, appareils et leur état, mises à jour de firmware, charge, mémoire et uptime de chaque appareil en ligne, nombre de clients |
| Compte View Only | L’API classique (/api/s/<site>/stat/*), sur /proxy/network/api/… sur une console | Tout ce qui précède, plus les clients par appareil et par type, les liens WAN, le statut WAN et Internet, et les alarmes |
Le statut WAN, Internet et des alarmes n’existe que dans l’API classique. Avec une clé, DumbMonit demande aussi à l’API classique le statut WAN et Internet avec la même clé ; si le contrôleur la refuse, ces séries sont simplement absentes, sans erreur.
Les alarmes sont les entrées du journal système « critical » d’UniFi sur
les dernières 24 heures (UniFi Network 8 et plus récent), ou les alarmes
non archivées sur les versions plus anciennes. C’est le seul POST que
DumbMonit envoie, et il ne fait que lire.
Une session ouverte avec le compte View Only est gardée d’une sonde à l’autre et rouverte quand elle expire : UniFi n’enregistre pas une nouvelle connexion chaque minute.
Ce qu’il surveille
Section intitulée « Ce qu’il surveille »Toutes les métriques sont préfixées dumbmonit_unifi_. Les séries
d’appareil portent device (son nom, ou son adresse MAC quand il n’en a
pas), mac, model et type (gateway, switch, access_point,
other).
| Métrique | Quoi | Labels |
|---|---|---|
info | valeur 1 | version, api (integration ou classic) |
devices | appareils par état : online, offline, pending, updating, adopting, adoption_failed, isolated, other | state |
devices_upgradable | appareils adoptés avec une mise à jour de firmware disponible | |
device_state | 0 en ligne, 1 hors ligne, 2 en attente d’adoption, 3 en mise à jour ou provisionnement, 4 en cours d’adoption, 5 adoption échouée, 6 isolé, 7 autre | labels d’appareil |
device_up | 1 en ligne ou en mise à jour, 0 hors ligne, isolé ou adoption échouée ; absent pour un appareil pas encore adopté | labels d’appareil |
device_upgradable | 1 quand une mise à jour de firmware est disponible | labels d’appareil, firmware |
device_uptime_seconds, device_cpu_percent, device_memory_percent | appareils en ligne seulement | labels d’appareil |
device_clients | clients connectés à l’appareil (compte View Only) | labels d’appareil |
wan_link_up | 1 quand un port WAN de la passerelle est actif ; un port désactivé n’a aucune série | labels d’appareil, wan (wan1, wan2) |
wan_up, internet_up | le statut WAN et Internet de la passerelle ; absent sans passerelle UniFi | |
internet_latency_seconds | latence mesurée par la passerelle | |
wan_availability_percent | disponibilité de chaque WAN sur les dernières 24 heures | wan |
subsystem_status | 0 ok, 1 avertissement, 2 erreur, 3 inconnu, pour wlan, wan, www, lan, vpn | subsystem |
clients | clients sur le site | |
clients_by_type | wireless, wired, guest, vpn (compte View Only) | type |
alarms | entrées du journal système critique des dernières 24 heures, ou alarmes non archivées | |
scrape_errors | appels qui ont échoué à la dernière sonde | |
port_enabled, port_up, port_speed_bps, port_full_duplex, port_uplink | ports de chaque commutateur ou passerelle en ligne (compte View Only, port_table) ; port_up est absent pour un port désactivé | device, mac, port (numéro en façade), port_name |
port_poe_enabled, port_poe_watts | PoE de chaque port | idem |
port_rx_bytes_total, port_tx_bytes_total, port_rx_errors_total, port_tx_errors_total | compteurs par port, tracés par le panneau de commutateur | idem |
port_neighbor_info | valeur 1, voisin LLDP du port (lldp_table) | idem, remote_chassis, remote_port |
Les règles intégrées qui s’appliquent : appareil UniFi hors ligne, Internet UniFi en panne, lien WAN UniFi en panne, CPU de passerelle UniFi élevé, appareil UniFi en attente d’adoption, mise à jour de firmware UniFi disponible, alarmes UniFi, plus Surveillance inaccessible.
Appareils
Section intitulée « Appareils »/rest/user (l’API classique, lue avec l’un ou l’autre identifiant) liste
chaque client que le contrôleur a jamais vu — la plupart d’un réseau
domestique, en pratique : téléphones qui passent, Wi-Fi invité, appareils
connectés qui ne reviennent jamais. Suivre tous ces appareils pour la
péremption enterrait l’alerte sous des appareils qui ne reviennent
simplement jamais, pas des appareils devenus silencieux. Par défaut, seuls
les clients que l’utilisateur a marqués d’une façon ou d’une autre
comptent : nommés dans UniFi, réservés sur une IP fixe, ou notés. L’option
Clients à surveiller en plus des marqués ajoute des adresses MAC ou
noms de client spécifiques, ou all pour suivre chaque client (non
recommandé sur autre chose qu’un petit réseau largement statique).
Les clients suivis sont publiés sous la famille générique partagée par
chaque intégration DumbMonit qui suit les appareils clients —
dumbmonit_client_device_*, préfixée sans unifi, documentée en entier
sous Appareils clients :
| Métrique | Quoi | Labels |
|---|---|---|
last_seen_timestamp_seconds | Dernière connexion, comme /rest/user la rapporte | device, type (Wired, Wireless ou Unknown), os (vide), user (vide), kind |
stale_seconds | Positif une fois qu’un client suivi a dépassé device_stale_days (3 par défaut) sans se connecter ; alimente la règle Appareil client périmé | device, type, os, user, kind, signal (toujours connection : UniFi n’a pas de sauvegarde à rapporter) |
Aller plus loin
Section intitulée « Aller plus loin »En plus de l’état des équipements, du WAN et des clients ci-dessus, DumbMonit lit, avec un compte local ou une clé d’API que l’API classique accepte :
- Santé des équipements : score de satisfaction, température et indicateur de surchauffe de chaque équipement en ligne.
- PoE : le budget PoE de chaque commutateur et ce que ses ports consomment.
- Wi-Fi : occupation du canal et nombre de clients de chaque radio (2,4, 5 et 6 GHz), nombre de clients Wi-Fi et combien ont un signal plus faible que -75 dBm.
- Test de débit de la passerelle : débit descendant, montant et latence du dernier test.
Rien n’envoie de commande ; si l’API classique refuse un appel, les séries correspondantes manquent simplement et la surveillance n’est pas en erreur.
Alertes par défaut
Section intitulée « Alertes par défaut »| Alerte | Se déclenche quand |
|---|---|
| UniFi device offline | Un équipement adopté est hors ligne, isolé ou en échec d’adoption depuis 5 minutes |
| UniFi Internet down / WAN link down | La passerelle n’a plus Internet, ou un lien WAN est tombé |
| UniFi subsystem in error | Le Wi-Fi, le LAN ou le VPN signale une erreur depuis 10 minutes |
| UniFi device overheating | Un équipement signale une surchauffe depuis 5 minutes |
| UniFi PoE budget nearly used | Un commutateur consomme plus de 90 % de son budget PoE depuis 15 minutes |
| UniFi Wi-Fi channel saturated | Le canal d’une radio est occupé plus de 80 % du temps depuis 30 minutes |
| UniFi Wi-Fi clients with a weak signal | Plus de 40 % d’au moins cinq clients Wi-Fi sont sous -75 dBm depuis une heure (information) |
| UniFi port errors | Un port journalise plus de 100 erreurs en 15 minutes |
| Mise à jour, équipement à adopter, alarmes, CPU de la passerelle | Comme avant |
Toutes les règles se modifient ou se désactivent dans Alertes.
La page de la surveillance
Section intitulée « La page de la surveillance »Le panneau au-dessus des graphiques lit ce que la sonde a stocké ; ouvrir la page n’interroge jamais UniFi. Il dit d’abord ce qui ne va pas (appareils hors ligne, Internet ou un lien WAN en panne, alarmes), puis les appareils par type avec leur état, firmware et charge, et les clients, puis le tableau des clients suivis avec leur dernière connexion.
Comment cela a été validé
Section intitulée « Comment cela a été validé »La connexion, le rôle View Only, les réponses d’erreur (mot de passe
refusé, site inconnu, clé refusée, session expirée) et les réponses d’un
contrôleur sans appareils ont été vérifiées contre UniFi Network 10.6.106,
auto-hébergé. Aucun appareil n’a pu y être adopté : la liste d’appareils, la
santé d’un site équipé, les clients connus (/rest/user) et les charges
utiles de l’Integration API sont validées contre la documentation
officielle.
Créer un accès en lecture seule dans UniFi Network
Section intitulée « Créer un accès en lecture seule dans UniFi Network »-
Pour une clé d’API sur une console UniFi OS : UniFi Network → Settings → Control Plane → Integrations → Create API Key. Nommez-la DumbMonit et copiez-la : elle n’est affichée qu’une fois.
-
Ou créez un compte local (requis pour l’état du WAN et des alarmes, et sur un serveur auto-hébergé) : Settings → Admins & Users → Create New, accès local uniquement.
dumbmonit -
Réglez le rôle UniFi Network de ce compte sur View Only.
-
Dans DumbMonit, saisissez l’adresse (unifi.lan, ou unifi.lan:8443 pour un serveur auto-hébergé) et collez la clé ou le compte.
-
Si le réseau n’est pas le site par défaut, réglez l’option Site sur le nom court affiché après /manage/ ou /network/ dans la barre d’adresse.
Droits requis
Section intitulée « Droits requis »- View Only (rôle UniFi Network) — Lit tout et ne change rien
Gardez l’authentification à deux facteurs désactivée pour ce seul compte local View Only, car un serveur de supervision ne peut pas saisir de code. Un mot de passe de propriétaire ou UI.com divulgué ouvrirait toutes les consoles qui lui sont liées.
UniFi connaît chaque client qui s’est un jour connecté, la plupart des téléphones de passage : seuls ceux nommés, réservés sur une IP fixe ou annotés dans UniFi sont surveillés par défaut, pour éviter une alerte par téléphone de visiteur. Listez-en d’autres dans l’option Clients to watch, ou saisissez all.
Identifiants
Section intitulée « Identifiants »| Identifiant | Champs |
|---|---|
| Clé d’API (console UniFi OS) | Une clé créée dans Settings → Control Plane → Integrations, envoyée comme X-API-KEY. |
| Compte View Only | Le nom d’utilisateur et le mot de passe du compte local View Only. |
Adresse : un nom d’hôte ou une IP (unifi.lan), host:port
(unifi.lan:8443 pour un serveur auto-hébergé), ou une URL complète ; une
adresse copiée depuis le navigateur, avec /manage/… ou /network/…, est
acceptée. Options : site (default), port (443), vérification du
certificat, délai de requête (15 s), clients à surveiller en plus des
marqués (vide, ou all), et péremption d’appareil (device_stale_days,
3 jours par défaut).