Intégration domotique ntopng, gratuite et open source
ntopng dans Gladys : débit réseau, hôtes et flux actifs, alertes et nouveaux hôtes.
Publiée par guim31
- Appareils
- Version 1.0.0
- Nécessite Gladys >=5.1.0
- ★ 0
ntopng observe le trafic d'une interface réseau (un port miroir, le côté LAN d'un routeur, un serveur de la maison) et dit qui parle à qui, combien, et ce qui paraît suspect. Cette intégration l'amène dans Gladys : un appareil par interface surveillée par ntopng, avec ses débits en réception et en émission, ses hôtes et flux actifs, et ses alertes. Des scènes peuvent réagir à une nouvelle alerte ntopng, à un hôte local jamais vu, ou à un débit qui dépasse un seuil, et un widget de tableau de bord montre le trafic et les alertes d'un coup d'œil. Tout reste sur votre réseau local.
Testée contre un vrai ntopng 7.0 Community (Docker), avec du trafic et un balayage de ports entre conteneurs de test. Pas encore sur un vrai réseau domestique : vos retours sont bienvenus dans les issues.
Ce qu'il vous faut
- Gladys Assistant 5.1.0 ou plus récent.
- ntopng 6 ou 7 (l'édition gratuite Community suffit), joignable depuis la machine de Gladys (port 3000 par défaut).
- Un utilisateur ntopng qui a le droit de lire les alertes (un administrateur, ou un utilisateur avec le droit « alertes »), et de préférence son jeton d'API.
L'intégration ne fait que lire : elle ne change jamais rien dans ntopng.
Mise en route
1. Obtenir un jeton d'API
Ouvrez ntopng dans un navigateur (http://<machine>:3000). Sur une installation
neuve, ntopng demande d'abord de changer le mot de passe admin par défaut :
faites-le, l'API reste fermée jusque-là. Ouvrez ensuite le menu utilisateur (en
haut à droite) → votre nom d'utilisateur → l'onglet du jeton → Generate, et
copiez le jeton.
2. Configurer l'intégration
Dans Gladys, Intégrations → ntopng → Configuration :
- Adresse de ntopng :
192.168.1.20,ntop.lan, ou l'adresse affichée par votre navigateur, commehttps://ntop.lan:3001(port 3000 si aucun n'est indiqué). - Jeton d'API : le jeton de l'étape 1. Sans jeton, remplissez Utilisateur (sans jeton) et Mot de passe (sans jeton).
- Intervalle de rafraîchissement : 1 minute par défaut (de 30 secondes à 5 minutes).
- Seuil de débit (Mbit/s) : seulement pour le déclencheur « Débit au-dessus du seuil » ; sinon, laissez vide.
- Accepter les certificats auto-signés : seulement pour une adresse en
https://, le certificat fourni avec ntopng étant auto-signé. - Langue des noms : la langue des noms des fonctionnalités et des textes de scène.
Cliquez ensuite sur Tester la connexion : il donne la version de ntopng, les interfaces, les hôtes actifs et les alertes en cours.
3. Ajouter les interfaces
Dans l'onglet Découverte, ajoutez les interfaces à suivre. Seules les interfaces ajoutées reçoivent des valeurs ; les déclencheurs de scène fonctionnent pour toutes.
Les appareils
Un appareil par interface, nommé ntopng <interface> :
| Fonctionnalité | Ce qu'elle montre |
|---|---|
| Joignable | ntopng répond et surveille encore l'interface |
| Réception | trafic reçu, en Mbit/s |
| Émission | trafic envoyé, en Mbit/s |
| Hôtes actifs | hôtes vus sur l'interface en ce moment |
| Hôtes locaux | ceux d'entre eux qui sont dans vos réseaux locaux |
| Flux actifs | connexions suivies en ce moment |
| Alertes en cours | alertes que ntopng tient ouvertes sur des hôtes ou sur l'interface |
| Flux en alerte | flux actifs porteurs d'une alerte (un balayage de ports en lève des milliers) |
| Gravité la plus haute | la pire d'entre elles : Aucune, Avis, Avertissement ou Erreur |
Les débits et les flux sont envoyés au plus une fois par minute ; les autres valeurs quand elles changent.
Tableau de bord
Le widget Trafic ntopng montre, pour une interface (celle choisie dans ses réglages, ou la seule), la réception, l'émission, les hôtes, les flux et les alertes en cours, puis la liste des alertes : celles en cours d'abord, les plus graves en tête, puis les alertes de flux des dernières 24 heures avec leur nombre. Avec plusieurs interfaces et aucune choisie, il montre les totaux et une ligne par interface. Le bouton Actualiser relit ntopng.
Scènes
Déclencheurs
- Nouvelle alerte ntopng : ntopng lève une alerte sur un hôte, un flux ou
une interface. Filtres : interface, gravité, type d'alerte (le nom anglais
affiché par ntopng, comme
Probing Attempt), adresse IP de l'hôte. Variables : interface, type d'alerte, gravité, levée sur, adresse IP et nom de l'hôte, description, occurrences. Un balayage de ports écrit une alerte de flux par sonde : elles sont regroupées par type et par hôte, et la même alerte se déclenche au plus une fois par heure. - Nouvel hôte local : ntopng voit un hôte local jamais vu auparavant, par son adresse MAC (sinon son adresse IP). Variables : interface, adresse IP, adresse MAC, nom de l'hôte. Les hôtes connus au démarrage de l'intégration ne sont pas annoncés.
- Débit au-dessus du seuil : réception plus émission d'une interface passe au-dessus du seuil de la configuration deux lectures de suite, ou revient sous 90 % de celui-ci. Filtre : le changement. Variables : réception, émission, total et seuil en Mbit/s.
Pour suivre la présence de vos appareils, NetAlertX fait mieux (balayages, présence par appareil) ; ntopng ne voit que les hôtes qui font passer du trafic par l'interface qu'il surveille.
Actions
- État d'une interface ntopng : lit une interface pour les actions
suivantes : réception, émission, hôtes, flux, alertes, gravité la plus haute,
et un résumé prêt à envoyer comme
eth0 : réception 12,3 Mbit/s, émission 1,5 Mbit/s, 24 hôte(s), 310 flux, aucune alerte. - Alertes ntopng récentes : les alertes en cours et les alertes de flux des dernières 24 heures, sur une interface ou toutes, avec leur nombre et un résumé.
Idées de scènes
- Nouvelle alerte ntopng, gravité Erreur → envoyer le message
{{triggerEvent.data.alert_type}} sur {{triggerEvent.data.host}} ({{triggerEvent.data.count}} fois). - Nouvel hôte local → envoyer
Nouvel appareil : {{triggerEvent.data.host_name}} {{triggerEvent.data.ip}} {{triggerEvent.data.mac}}. - Débit au-dessus du seuil la nuit → mettre les sauvegardes en pause, et les reprendre sur « Revenu en dessous ».
- Chaque soir à 21 h → Alertes ntopng récentes → si le nombre dépasse 0, envoyer le résumé.
Dépannage
- « ne répond pas » : vérifiez l'adresse et le port dans un navigateur ; un pare-feu peut bloquer le port 3000.
- « connectez-vous une fois à ntopng et changez le mot de passe admin par
défaut » : ntopng renvoie chaque requête vers la page du mot de passe tant
que celui d'
adminn'est pas changé. - « jeton d'API ou mot de passe refusé » : générez un nouveau jeton, ou vérifiez l'utilisateur et le mot de passe.
- « cet utilisateur ntopng n'a pas le droit de lire les alertes » : les valeurs arrivent quand même, mais aucun événement d'alerte : donnez le droit « alertes » à l'utilisateur, ou utilisez un administrateur.
- « l'adresse redirige » : ntopng ne sert que du HTTPS : saisissez
l'adresse en
https://(port 3001 par défaut). - ntopng lève « Clear-Text Credentials » pour Gladys : avec un utilisateur et un mot de passe en HTTP, ntopng voit passer le mot de passe en clair sur le réseau qu'il surveille. Utilisez un jeton d'API, ou le HTTPS.
- ntopng en Docker ne montre presque rien : il surveille son propre
conteneur ; lancez-le avec
--network host(sur la machine qui voit le trafic) ou sur un port miroir. - Plus de détails avec la variable d'environnement
LOG_LEVEL=debugsur l'intégration.
Limites
- Une seule instance ntopng, 8 interfaces au plus.
- Sont lues les alertes en cours (hôtes, interface) et les alertes de flux ; les autres familles d'alertes de ntopng (réseaux, système, SNMP de l'édition Enterprise) ne le sont pas.
- Les événements d'alertes de flux demandent le stockage SQLite des éditions Community et Pro ; avec ClickHouse (Enterprise), ils sont désactivés.
- Conçue pour l'édition Community : les fonctions des éditions payantes (politiques de trafic, SNMP, nProbe) ne sont pas lues.
- L'intégration lit les valeurs courantes à chaque rafraîchissement : elle n'importe pas l'historique de ntopng.
- Sans lien avec ntop.
Paramètres de configuration
Voici les paramètres demandés par ntopng dans son écran de configuration dans Gladys.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| Votre ntopng | section | Non | Saisissez l'adresse de ntopng et un jeton d'API (ou un utilisateur et son mot de passe). Chaque interface surveillée par ntopng devient un appareil : ajoutez celles voulues depuis l'onglet Découverte. L'édition Community suffit. |
| Adresse de ntopng | string | Non | Port 3000 par défaut : 192.168.1.20, ntop.lan ou https://ntop.lan:3001. |
| Jeton d'API | secret | Non | Recommandé. Dans ntopng : menu utilisateur (en haut à droite) → votre utilisateur → onglet du jeton → Générer. |
| Utilisateur (sans jeton) | string | Non | Seulement sans jeton d'API : un utilisateur ntopng qui a le droit de lire les alertes. |
| Mot de passe (sans jeton) | secret | Non | |
| Options | section | Non | Seules les interfaces ajoutées à Gladys reçoivent des valeurs ; les déclencheurs de scène fonctionnent pour toutes. |
| Intervalle de rafraîchissement | select | Non | Fréquence de lecture de ntopng. |
| Seuil de débit (Mbit/s) | string | Non | Pour le déclencheur « Débit au-dessus du seuil » : réception plus émission d'une interface, en Mbit/s. Vide : désactivé. |
| Accepter les certificats auto-signés | boolean | Non | Seulement pour une adresse en https:// : le certificat fourni avec ntopng est auto-signé. |
| Langue des noms | select | Non | Langue des noms des fonctionnalités (fixés à l'ajout d'un appareil), des textes de scène et du test de connexion. |
Comment installer ntopng dans Gladys
- Dans Gladys, ouvrez Intégrations : ntopng apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
- Cliquez sur Installer. Gladys télécharge l'image Docker (
ghcr.io/guim31/gladys-ntopng:1.0.0), la démarre dans un bac à sable isolé du cœur, et génère l'interface de l'intégration (appareils, découverte et configuration). - Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
- Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/guim31/gladys-ntopng.
ntopng nécessite Gladys >=5.1.0. Le catalogue dans Gladys se rafraîchit toutes les heures : une nouvelle version est donc disponible au plus tard une heure après sa sortie.
Vous n'utilisez pas encore Gladys ? C'est gratuit et open source : suivez le guide d'installation pour démarrer.
À propos des intégrations externes
ntopng est une intégration externe : une intégration communautaire empaquetée dans un conteneur Docker et publiée sur GitHub, que Gladys installe en un clic et exécute dans un bac à sable isolé de son cœur. Elle est publiée et maintenue par guim31, et non par l'équipe cœur de Gladys.
- Parcourir toutes les intégrations, natives et communautaires
- Créer et publier votre propre intégration externe
- Code source sur GitHub — source de cette documentation