HYPHApar S33D
Documentation › Intégrations

Réseau, stockage et sauvegardes auto-hébergés : Pi-hole, AdGuard Home, Unbound, Caddy, MinIO, Mosquitto, Proxmox Backup Server, Borg, restic

Requêtes DNS et blocages, serveurs amont, capacité du stockage objet, clients MQTT, et surtout l'âge et l'état de la dernière sauvegarde de chaque groupe ou dépôt, lus en lecture seule.

En un coup d'œil

LogicielCollecteActivationEspace de nomsÉprouvé sur
Pi-holeAPI REST de Pi-hole 6 (/api)auto si /etc/pihole existe, ou password posépihole.*Pi-hole 6.6 (FTL 6.9)
AdGuard HomeAPI /control (compte de l'interface)dès que username et password sont posésadguard.*AdGuard Home 1.0.0
Unboundunbound-control stats_noresetauto si /etc/unbound/unbound.conf existeunbound.*Unbound 1.26.2 (Debian 13)
CaddyAPI d'administration (:2019) + profil OpenMetrics caddysonde auto sur 127.0.0.1:2019 ; profil à déclarercaddy.*Caddy 2.11.9
MinIOprofils OpenMetrics minio et minio_bucketà déclarerminio.*MinIO RELEASE.2025-10-15T17-29-55Z
Mosquittosujets $SYS en MQTT 3.1.1auto si /etc/mosquitto existe, ou username posémosquitto.*Mosquitto 2.1.4
Proxmox Backup ServerAPI (:8007), jeton au rôle Auditdès que le jeton est poséproxmox_backup.*PBS 4.2.14
Borgborg list --json (et borg info)dès qu'un dépôt est déclaréborg.*Borg 1.4.4 (serveur 1.4.0)
resticrestic snapshots --json (et restic stats)dès qu'un dépôt est déclarérestic.*restic 0.18.1, rest-server

Chaque logiciel a été lancé dans un environnement d'essai de S33D, en conteneur, avec ses vraies données : requêtes DNS réelles, sauvegardes réelles, puis pannes provoquées (sauvegarde interrompue, bloc corrompu, serveur amont arrêté). Les sondes acceptent des instances (instances:, une entrée nommée par serveur supplémentaire) et des étiquettes fixes (tags:) posées sur toutes leurs mesures et tous leurs contrôles. Rien n'est jamais écrit dans ces logiciels.

Pi-hole

Pi-hole 6 sert une API REST sur son serveur web (port 80 et 443 par défaut). Créez un mot de passe d'application (Réglages › Interface web / API › Configurer le mot de passe d'application) : il ne demande pas la double authentification et peut être retiré sans toucher au mot de passe de l'interface.

integrations:
  pihole:
    url: http://127.0.0.1           # ou https://127.0.0.1 avec insecure: true (certificat autosigné)
    password: "mot de passe d'application"

L'agent ouvre une session au premier relevé, la garde tant que Pi-hole l'accepte et la ferme à son arrêt : Pi-hole limite le nombre de sessions ouvertes. Un Pi-hole sans mot de passe se lit sans password.

MesureSens
pihole.queries.total, .blocked, .cached, .forwarded, .unique_domainssur les 24 dernières heures (fenêtre glissante de FTL)
pihole.queries.percent_blockedpart des requêtes bloquées (%)
pihole.queries.frequencyrequêtes par seconde (moyenne récente de FTL)
pihole.queries.by_status (status), pihole.queries.by_reply (reply)requêtes par traitement (gravity, cache, forwarded…) et par réponse
pihole.clients.active, pihole.clients.totalclients
pihole.gravity.domains_blocked, pihole.gravity.agedomaines en liste, secondes depuis la dernière mise à jour des listes
pihole.blocking.enabled1 si le blocage est actif
pihole.messages, pihole.messages.by_typeavertissements de FTL (Outils › Diagnostic)
pihole.updates_availablecomposants (core, web, FTL) dont Pi-hole annonce une version plus récente

Contrôles : pihole.can_connect et pihole.blocking (avertissement : blocage coupé, avec le temps restant ; critique : blocage en échec).

AdGuard Home

L'agent lit /control/status, /control/stats et /control/filtering/status avec le compte de l'interface, en authentification de base. Il n'appelle jamais /control/version.json (qui interroge les serveurs d'AdGuard) ni aucune route d'écriture.

integrations:
  adguard:
    url: http://127.0.0.1:3000
    username: admin
    password: "…"
MesureSens
adguard.queries, .queries.blocked, .queries.percent_blockedsur la fenêtre de statistiques d'AdGuard Home (24 h par défaut)
adguard.queries.safebrowsing, .safesearch, .parentalréponses remplacées par la navigation sécurisée, la recherche sécurisée, le contrôle parental
adguard.processing_timetemps de traitement moyen (ms)
adguard.upstream.responses, adguard.upstream.avg_time (upstream)réponses et temps moyen (ms) de chaque serveur amont
adguard.filter.rules, adguard.filter.age (filter)règles et âge (s) de chaque liste active
adguard.filters.enabled, .rules, .empty, .oldest_update_agelistes actives, règles au total, listes vides ou jamais téléchargées, plus vieille mise à jour
adguard.running, adguard.protection_enabled, adguard.filtering.enabled1/0

Contrôles : adguard.can_connect et adguard.protection (avertissement : protection coupée ; critique : serveur DNS arrêté).

Unbound

Activez le canal de contrôle (le paquet Debian le fait déjà, sur une socket Unix), et de préférence les statistiques détaillées :

server:
    extended-statistics: yes
remote-control:
    control-enable: yes
    control-interface: /run/unbound.ctl
integrations:
  unbound:
    command: unbound-control                   # « docker exec unbound unbound-control » en conteneur
    # config_file: /etc/unbound/unbound.conf   # passé par -c

L'agent lance unbound-control stats_noreset toutes les 30 secondes, sans shell : les compteurs ne sont pas remis à zéro. Les compteurs donnent un écart par intervalle ; si un autre outil lit stats (qui remet à zéro), un seul intervalle est perdu.

Contrôle unbound.can_connect : critique si unbound-control échoue (Unbound arrêté, canal de contrôle coupé, clés illisibles).

Caddy

Caddy publie ses mesures Prometheus sur son API d'administration (/metrics, port 2019). Celles des serveurs HTTP demandent l'option globale metrics :

{
	metrics
}
integrations:
  openmetrics:
    - profile: caddy                 # http://127.0.0.1:2019/metrics
  caddy:
    url: http://127.0.0.1:2019       # sonde de l'API d'administration (auto)

Profil caddy : caddy.http.requests, caddy.http.requests_in_flight, caddy.http.request_errors (par server et handler), caddy.http.request.duration (histogramme : .count par code = réponses par code, .p95…), caddy.http.response.duration, caddy.http.request.size, caddy.http.response.size, caddy.reverse_proxy.upstream.healthy (1/0 par upstream), caddy.config.last_reload_successful, caddy.config.last_reload_success_timestamp, caddy.process.resident_memory, caddy.go.goroutines.

La sonde caddy lit en GET seulement /config/apps/http/servers (caddy.servers, caddy.routes) et /reverse_proxy/upstreams (caddy.upstream.requests : requêtes en cours, caddy.upstream.fails : échecs comptés par la santé passive, caddy.upstreams, caddy.upstreams.failing). Contrôle caddy.can_connect. L'API d'administration ne doit jamais être ouverte au réseau.

MinIO

MinIO publie ses mesures sur /minio/v2/metrics/cluster (grappe) et /minio/v2/metrics/bucket (par seau). Créez le jeton Prometheus de MinIO, puis rangez la valeur de bearer_token dans un fichier lisible par l'agent seul :

mc admin prometheus generate monalias cluster
integrations:
  openmetrics:
    - profile: minio                 # http://127.0.0.1:9000/minio/v2/metrics/cluster
      bearer_token_file: /etc/hypha/minio.token
    - profile: minio_bucket          # /minio/v2/metrics/bucket, même jeton
      bearer_token_file: /etc/hypha/minio.token

Sans jeton, MinIO répond 403, sauf MINIO_PROMETHEUS_AUTH_TYPE=public. Dans une grappe, un seul agent suffit (le point de grappe agrège tous les nœuds ; étiquette server).

MinIO ne publie plus d'image ni de binaire de son édition libre : la version éprouvée a été construite depuis ses sources officielles.

Mosquitto

L'agent se connecte au courtier en MQTT 3.1.1, s'abonne à $SYS/broker/# en QoS 0, lit les valeurs retenues, puis se déconnecte : il ne publie jamais. Donnez-lui un compte qui ne lit que $SYS :

# mosquitto_passwd -b /etc/mosquitto/passwd hypha "…"
# ACL (acl_file) :
user hypha
topic read $SYS/#
integrations:
  mosquitto:
    url: mqtt://127.0.0.1:1883       # mqtts://hôte:8883 en TLS (ca_file, insecure)
    username: hypha
    password: "…"

Contrôle mosquitto.can_connect : compte refusé (CONNACK 4 ou 5), abonnement refusé par l'ACL, ou aucun sujet $SYS reçu (sys_interval 0).

Proxmox Backup Server

Créez un utilisateur et un jeton d'API au rôle Audit, sur le chemin /, pour l'utilisateur ET pour le jeton (les droits d'un jeton sont l'intersection des deux) :

proxmox-backup-manager user create hypha@pbs
proxmox-backup-manager acl update / Audit --auth-id hypha@pbs
proxmox-backup-manager user generate-token hypha@pbs lecture
proxmox-backup-manager acl update / Audit --auth-id 'hypha@pbs!lecture'
proxmox-backup-manager cert info | grep Fingerprint
integrations:
  proxmox_backup:
    url: https://127.0.0.1:8007
    token_id: "hypha@pbs!lecture"
    token_secret: "…"                # valeur rendue par generate-token
    fingerprint: "af:c8:fd:…"        # empreinte SHA-256 du certificat (ou ca_file, ou insecure: true)
    # interval: 1m
    # max_groups: 500                # groupes de sauvegarde suivis par magasin

L'abonnement n'est jamais lu. Par relevé :

Contrôles : proxmox_backup.can_connect, proxmox_backup.datastore (critique : magasin en erreur), proxmox_backup.job (dernier passage de chaque travail de vérification, d'élagage, de synchronisation et du ramasse-miettes ; critique en échec), proxmox_backup.backup (dernière tâche de sauvegarde de chaque groupe sur 7 jours, relue toutes les 5 min : critique en échec, levé dès que la suivante réussit).

Borg et restic

L'agent lance l'outil installé sur la machine, sans shell et sans verrou : borg --bypass-lock, restic --no-lock. Une sauvegarde, un élagage ou une vérification en cours ne sont jamais gênés ni retardés par la supervision. Chaque dépôt est relu toutes les 15 minutes.

integrations:
  borg:
    repositories:
      - name: serveur
        repository: ssh://borg@sauvegarde.exemple/./depot
        passphrase_file: /etc/hypha/borg-serveur.pass     # root, droits 600 ou 400
        rsh: "ssh -i /root/.ssh/borg -o BatchMode=yes"
  restic:
    repositories:
      - name: nas
        repository_file: /etc/hypha/restic-nas.repo        # adresse avec identifiants (rest:, s3:…)
        password_file: /etc/hypha/restic-nas.pass
      - name: local
        repository: /srv/restic
        password_file: /etc/hypha/restic-local.pass
    # stats: true      # taille des dépôts (borg info, restic stats), relue toutes les 6 h
    # interval: 15m
    # timeout: 2m
MesureSens
borg.last_archive.agesecondes depuis le début de la dernière archive complète
borg.archives, borg.checkpointsarchives complètes, points de reprise (.checkpoint)
borg.repository.last_modified.agesecondes depuis la dernière écriture dans le dépôt
borg.repository.unique_csize, .unique_size, .total_sizeavec stats: true : place occupée (dédupliquée et compressée), dédupliquée, totale
restic.last_snapshot.agesecondes depuis le dernier instantané
restic.snapshots, restic.host.last_snapshot.age (restic_host)instantanés, âge du dernier par machine
restic.last_snapshot.files, .bytes, .added, .durationdernier instantané (restic 0.17 ou plus)
restic.repository.size, .uncompressed_size, .compression_ratioavec stats: true

Étiquette repository (le name du dépôt). Contrôles : borg.can_connect et restic.can_connect (dépôt lisible, critique sinon : serveur injoignable, phrase de passe refusée, fichier mal protégé), borg.backup (avertissement : la dernière sauvegarde s'est arrêtée en route, point de reprise plus récent que la dernière archive complète ; critique : aucune archive) et restic.backup (critique : aucun instantané).

Modèles de moniteurs

Tableaux prêts

Tableaux de bord › Catalogue : Pi-hole, AdGuard Home et Unbound (famille DNS), Caddy (Web), MinIO (Stockage), Mosquitto (Files de messages), Proxmox Backup Server, Borg et restic (Sauvegardes).

Ce qui n'a pas été éprouvé

Mise à jour : 21 novembre 2026