Aller au contenu principal

Intégration domotique Unbound, gratuite et open source

Intégration Unbound pour Gladys Assistant

Résolveur DNS Unbound : requêtes, cache, temps de récursion, SERVFAIL, alertes, vider le cache.

Voir sur GitHubToutes les intégrations

Suivez votre résolveur DNS Unbound depuis Gladys, sur votre réseau local : requêtes par minute, taux de réponse du cache, temps de récursion moyen, réponses SERVFAIL et NXDOMAIN, temps de fonctionnement, et une alerte quand il ne répond plus, échoue trop souvent ou reçoit une avalanche de requêtes. Unbound est souvent le résolveur récursif placé derrière Pi-hole, AdGuard Home ou Blocky : eux bloquent les publicités, Unbound répond au reste. Cette intégration surveille le résolveur, pas le blocage.

Testée contre un vrai Unbound 1.25.2 (paquet Alpine, dans Docker, avec les certificats d'unbound-control-setup et de vraies requêtes dig), pas encore avec une vraie installation de Gladys : vos retours sont les bienvenus. Si quelque chose ne marche pas comme décrit, dites-le sur le forum Gladys ou dans les issues.

Ce qu'il faut​

  • Gladys Assistant 5.1.0 ou plus récent.
  • Unbound avec son contrôle à distance activé, le canal qu'utilise unbound-control. Gladys envoie les mêmes commandes que unbound-control stats_noreset et unbound-control status : elle ne fait que lire, et ne lance jamais stats, qui remet les compteurs à zéro.
  • Pour les chiffres SERVFAIL et NXDOMAIN, les statistiques étendues.

Dans unbound.conf :

server:
  extended-statistics: yes

remote-control:
  control-enable: yes
  # Une adresse de la machine Unbound que Gladys peut atteindre (pas
  # 127.0.0.1 : Gladys fait tourner l'intégration dans son propre conteneur).
  control-interface: 192.168.1.2
  control-port: 8953

Créez ensuite les certificats une fois, sur la machine Unbound, puis redémarrez Unbound :

sudo unbound-control-setup
sudo systemctl restart unbound

unbound-control-setup écrit trois fichiers, en général dans /etc/unbound : unbound_server.pem, unbound_control.pem et unbound_control.key (plus la clé du serveur, qui reste là). Vérifiez que sudo unbound-control status fonctionne sur la machine avant de continuer.

Si statistics-interval est réglé dans unbound.conf, réglez aussi statistics-cumulative: yes : sinon Unbound remet ses compteurs à zéro à chaque intervalle et les taux sont faux.

Configuration​

Dans Gladys, Intégrations → Unbound → Configuration :

  1. Adresse : l'adresse IP ou le nom de la machine Unbound, avec :port si le port de contrôle n'est pas 8953.
  2. Nom : le nom de l'appareil dans Gladys (facultatif).
  3. Connexion : TLS avec certificats (par défaut dans Unbound), ou TCP simple si unbound.conf indique control-use-cert: no. Le TCP simple n'a aucun mot de passe : quiconque atteint le port peut arrêter Unbound. Ne le gardez que pour un port fermé au reste du réseau.
  4. Certificats : ouvrez chaque fichier avec un éditeur de texte (sudo cat /etc/unbound/unbound_control.pem) et collez tout son contenu, de -----BEGIN à -----END, dans Certificat du serveur (unbound_server.pem), Certificat client (unbound_control.pem) et Clé client (unbound_control.key). Le champ ne garde qu'une ligne : c'est normal, l'intégration remet les retours à la ligne. La clé est conservée comme secret, jamais réaffichée ni écrite dans les logs.
  5. Options : l'intervalle de rafraîchissement (1 minute par défaut), les deux seuils d'alerte, Autoriser à vider le cache (désactivé par défaut), et la langue des noms de fonctionnalités.
  6. Enregistrez, puis Tester la connexion : elle affiche la version d'Unbound, la connexion utilisée, son temps de fonctionnement et si les statistiques étendues sont actives.
  7. Dans l'onglet Découverte, ajoutez l'appareil.

L'appareil​

Un appareil pour le serveur, avec ces fonctionnalités :

FonctionnalitéCe qu'elle montre
Joignable1 quand le contrôle à distance répond, 0 sinon
Requêtes DNS par minuteRequêtes reçues, entre les deux dernières lectures
Taux de réponse du cachePart des requêtes servies par le cache, 15 dernières minutes (%)
Temps de récursion moyenTemps pour résoudre un nom absent du cache, 15 dernières minutes
SERVFAIL par minuteRésolutions en échec (statistiques étendues)
NXDOMAIN par minuteNoms qui n'existent pas (statistiques étendues)
Temps de fonctionnementHeures depuis le démarrage d'Unbound
VersionVersion d'Unbound

Sans les statistiques étendues, l'appareil n'a ni SERVFAIL ni NXDOMAIN ; activez-les et Gladys propose Mettre à jour dans l'onglet Découverte. Les taux apparaissent à partir de la deuxième lecture. Après un redémarrage d'Unbound, ses compteurs repartent de zéro : les taux reviennent une lecture plus tard.

Tableau de bord​

Le widget Unbound montre trois tuiles (requêtes par minute, taux de cache, temps de récursion) et une liste : l'état du résolveur, SERVFAIL et NXDOMAIN par minute (SERVFAIL en orange au-dessus de son seuil d'alerte), temps de fonctionnement et version. Quand Autoriser à vider le cache est activé, il a aussi un bouton Vider le cache.

Scènes​

Déclencheurs​

  • Unbound ne répond plus : deux lectures de suite sans réponse (la deuxième 15 secondes après la première). Variables : nom du serveur, appareil, erreur.
  • Unbound répond de nouveau : retour après une panne, avec les minutes sans réponse.
  • SERVFAIL d'Unbound au-dessus du seuil : les réponses SERVFAIL par minute atteignent Alerte SERVFAIL de la configuration (20 par défaut, 0 la désactive). Il se déclenche une fois, puis de nouveau seulement après un retour sous le seuil. Statistiques étendues requises.
  • Requêtes Unbound qui s'emballent : les requêtes par minute atteignent Alerte d'emballement (2000 par défaut, 0 la désactive), pour un appareil qui boucle ou un logiciel malveillant. Même règle d'une seule fois.

Actions​

  • Lire les statistiques Unbound : lit Unbound maintenant. Donne une phrase (« Unbound : 120 requêtes par minute, 85 % servies par le cache, 32 ms par récursion. ») pour un message ou une annonce vocale, et les chiffres pour une condition.
  • Vider le cache d'Unbound : vide le cache, pour un domaine et tout ce qui est en dessous, ou en entier quand le champ est vide. Refusé tant qu'Autoriser à vider le cache n'est pas activé. Utile après la modification d'un enregistrement DNS à la maison.

Idées de scènes​

  • Unbound ne répond plus → envoyer un message : « Le DNS de la maison est en panne ». Ajoutez Unbound répond de nouveau pour la bonne nouvelle.
  • SERVFAIL d'Unbound au-dessus du seuil → un message avec le taux : le lien Internet ou les serveurs amont ont un problème.
  • Chaque matin à 8 h → Lire les statistiques Unbound → envoyer la phrase.
  • Requêtes Unbound qui s'emballent → une notification, pour chercher l'appareil qui s'emballe.

Dépannage​

  • « ne répond pas » : mauvaise adresse ou mauvais port, Unbound arrêté, ou control-interface encore sur 127.0.0.1 (par défaut). Gladys fait tourner l'intégration dans un conteneur : il lui faut une adresse du réseau, et un pare-feu ouvert sur le port 8953 pour la machine Gladys.
  • « TLS refusé » : un des trois champs de certificats ne correspond pas aux fichiers de cet Unbound (ils changent à chaque unbound-control-setup -r), ou Unbound est en mode simple (control-use-cert: no) : choisissez TCP simple.
  • « connexion fermée : TLS attendu ? » : TCP simple est choisi mais Unbound attend du TLS : choisissez TLS avec certificats.
  • « collez tout le fichier » : un champ de certificat ne contient qu'une partie du fichier ; copiez tout, lignes -----BEGIN et -----END comprises.
  • Ni SERVFAIL ni NXDOMAIN : ajoutez extended-statistics: yes sous server:, redémarrez Unbound, puis Mettez à jour l'appareil dans l'onglet Découverte.
  • Taux bizarres ou absents : un autre outil lance unbound-control stats (qui remet les compteurs à zéro), ou statistics-interval est réglé sans statistics-cumulative: yes.
  • Logs : Intégrations → Unbound → Logs. Ajoutez LOG_LEVEL=debug pour voir chaque lecture.

Limites​

  • Un seul serveur Unbound par installation de l'intégration.
  • Développée avec un vrai Unbound dans Docker, sans vraie installation de Gladys : vos retours sont les bienvenus.
  • Les taux par minute sont mesurés entre deux lectures : un pic plus court que l'intervalle de rafraîchissement est lissé.
  • Le taux de cache et le temps de récursion couvrent les 15 dernières minutes ; juste après le démarrage de l'intégration, ils couvrent le temps depuis le démarrage d'Unbound.
  • Par un socket Unix seulement (control-interface: /run/unbound.ctl), Unbound est injoignable depuis le conteneur de Gladys : utilisez une adresse réseau.
  • Sans lien avec NLnet Labs.

Paramètres de configuration​

Voici les paramètres demandés par Unbound dans son écran de configuration dans Gladys.

ParamètreTypeObligatoireDescription
Votre serveur UnboundsectionNonGladys lit Unbound par son contrôle à distance (remote-control: dans unbound.conf, port 8953) : control-enable: yes, et control-interface sur une adresse que Gladys atteint.
AdressestringOuiAdresse IP ou nom du serveur, avec :port si ce n'est pas 8953.
NomstringNonNom de l'appareil dans Gladys. Vide : « Unbound » suivi de l'adresse.
ConnexionselectNonTLS avec les certificats d'unbound-control-setup (par défaut dans Unbound), ou TCP simple si unbound.conf indique control-use-cert: no.
Certificats (TLS)sectionNonOuvrez chaque fichier créé par unbound-control-setup (souvent dans /etc/unbound) et collez tout son contenu, de -----BEGIN à -----END. Inutile en TCP simple.
Certificat du serveur (unbound_server.pem)stringNon
Certificat client (unbound_control.pem)stringNon
Clé client (unbound_control.key)secretNonConservée par Gladys, jamais réaffichée ni écrite dans les logs.
OptionssectionNon
Intervalle de rafraîchissementselectNonFréquence de lecture d'Unbound. Les taux par minute sont mesurés entre deux lectures.
Alerte SERVFAIL (par minute)numberNonL'événement de scène se déclenche quand les réponses SERVFAIL atteignent ce rythme (extended-statistics: yes requis). 0 : désactivé.
Alerte d'emballement (requêtes par minute)numberNonL'événement de scène se déclenche quand les requêtes atteignent ce rythme : un appareil qui s'emballe, une boucle. 0 : désactivé.
Autoriser à vider le cachebooleanNonDésactivé par défaut : Gladys ne fait alors que lire Unbound. Activé : l'action de scène et le bouton du widget peuvent vider le cache (flush_zone).
Langue des noms de fonctionnalitésselectNonNoms donnés aux fonctionnalités à l'ajout de l'appareil, et textes des événements et actions de scène.

Comment installer Unbound dans Gladys​

  1. Dans Gladys, ouvrez Intégrations : Unbound apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
  2. Cliquez sur Installer. Gladys télécharge l'image Docker (ghcr.io/guim31/gladys-unbound: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).
  3. Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
  4. Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/guim31/gladys-unbound.

Unbound 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​

Unbound 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.

Inscrivez-vous à la newsletter Gladys Assistant

Quelques emails par mois sur les nouveautés et l'actualité du projet. Envoyés par Pierre-Gilles Leymarie, le fondateur du projet. Désinscription possible à tout moment 🙂
Dernière mise à jour le