HYPHAby S33D
Documentation › Integrations

Self-hosted network, storage and backups: Pi-hole, AdGuard Home, Unbound, Caddy, MinIO, Mosquitto, Proxmox Backup Server, Borg, restic

DNS queries and blocking, upstream servers, object storage capacity, MQTT clients, and above all the age and state of the last backup of every group or repository, read-only.

At a glance

SoftwareCollectionActivationNamespaceTested on
Pi-holePi-hole 6 REST API (/api)auto if /etc/pihole exists, or password setpihole.*Pi-hole 6.6 (FTL 6.9)
AdGuard Home/control API (web interface account)as soon as username and password are setadguard.*AdGuard Home 1.0.0
Unboundunbound-control stats_noresetauto if /etc/unbound/unbound.conf existsunbound.*Unbound 1.26.2 (Debian 13)
Caddyadmin API (:2019) + OpenMetrics profile caddyprobe auto on 127.0.0.1:2019; profile to declarecaddy.*Caddy 2.11.9
MinIOOpenMetrics profiles minio and minio_bucketto declareminio.*MinIO RELEASE.2025-10-15T17-29-55Z
Mosquitto$SYS topics over MQTT 3.1.1auto if /etc/mosquitto exists, or username setmosquitto.*Mosquitto 2.1.4
Proxmox Backup ServerAPI (:8007), token with the Audit roleas soon as the token is setproxmox_backup.*PBS 4.2.14
Borgborg list --json (and borg info)as soon as a repository is declaredborg.*Borg 1.4.4 (server 1.4.0)
resticrestic snapshots --json (and restic stats)as soon as a repository is declaredrestic.*restic 0.18.1, rest-server

Each piece of software was run in an S33D test environment, in a container, with real data: real DNS queries, real backups, then provoked failures (interrupted backup, corrupted chunk, stopped upstream). The probes accept instances (instances:, one named entry per extra server) and fixed tags (tags:) added to all their metrics and checks. Nothing is ever written to this software.

Pi-hole

Pi-hole 6 serves a REST API on its web server (ports 80 and 443 by default). Create an app password (Settings › Web interface / API › Configure app password): it skips two-factor authentication and can be removed without touching the interface password.

integrations:
  pihole:
    url: http://127.0.0.1           # or https://127.0.0.1 with insecure: true (self-signed certificate)
    password: "app password"

The agent opens a session on the first collection, keeps it while Pi-hole accepts it and closes it when it stops: Pi-hole limits the number of open sessions. A Pi-hole without a password is read without password.

MetricMeaning
pihole.queries.total, .blocked, .cached, .forwarded, .unique_domainsover the last 24 hours (FTL sliding window)
pihole.queries.percent_blockedshare of blocked queries (%)
pihole.queries.frequencyqueries per second (recent FTL average)
pihole.queries.by_status (status), pihole.queries.by_reply (reply)queries by handling (gravity, cache, forwarded…) and by reply
pihole.clients.active, pihole.clients.totalclients
pihole.gravity.domains_blocked, pihole.gravity.agelisted domains, seconds since the last list update
pihole.blocking.enabled1 when blocking is on
pihole.messages, pihole.messages.by_typeFTL warnings (Tools › Diagnosis)
pihole.updates_availablecomponents (core, web, FTL) for which Pi-hole reports a newer version

Checks: pihole.can_connect and pihole.blocking (warning: blocking disabled, with the remaining time; critical: blocking failed).

AdGuard Home

The agent reads /control/status, /control/stats and /control/filtering/status with the web interface account, over basic authentication. It never calls /control/version.json (which queries AdGuard's servers) nor any write route.

integrations:
  adguard:
    url: http://127.0.0.1:3000
    username: admin
    password: "…"
MetricMeaning
adguard.queries, .queries.blocked, .queries.percent_blockedover the AdGuard Home statistics window (24 h by default)
adguard.queries.safebrowsing, .safesearch, .parentalanswers replaced by safe browsing, safe search, parental control
adguard.processing_timeaverage processing time (ms)
adguard.upstream.responses, adguard.upstream.avg_time (upstream)answers and average time (ms) of each upstream server
adguard.filter.rules, adguard.filter.age (filter)rules and age (s) of each enabled list
adguard.filters.enabled, .rules, .empty, .oldest_update_ageenabled lists, total rules, empty or never downloaded lists, oldest update
adguard.running, adguard.protection_enabled, adguard.filtering.enabled1/0

Checks: adguard.can_connect and adguard.protection (warning: protection disabled; critical: DNS server stopped).

Unbound

Enable the control channel (the Debian package already does, on a Unix socket), and preferably extended statistics:

server:
    extended-statistics: yes
remote-control:
    control-enable: yes
    control-interface: /run/unbound.ctl
integrations:
  unbound:
    command: unbound-control                   # "docker exec unbound unbound-control" in a container
    # config_file: /etc/unbound/unbound.conf   # passed with -c

The agent runs unbound-control stats_noreset every 30 seconds, without a shell: counters are not reset. Counters give a per-interval delta; if another tool reads stats (which resets), a single interval is lost.

Check unbound.can_connect: critical when unbound-control fails (Unbound stopped, control channel disabled, unreadable keys).

Caddy

Caddy serves its Prometheus metrics on its admin API (/metrics, port 2019). HTTP server metrics need the global metrics option:

{
	metrics
}
integrations:
  openmetrics:
    - profile: caddy                 # http://127.0.0.1:2019/metrics
  caddy:
    url: http://127.0.0.1:2019       # admin API probe (auto)

Profile caddy: caddy.http.requests, caddy.http.requests_in_flight, caddy.http.request_errors (by server and handler), caddy.http.request.duration (histogram: .count by code = responses per code, .p95…), caddy.http.response.duration, caddy.http.request.size, caddy.http.response.size, caddy.reverse_proxy.upstream.healthy (1/0 per upstream), caddy.config.last_reload_successful, caddy.config.last_reload_success_timestamp, caddy.process.resident_memory, caddy.go.goroutines.

The caddy probe only reads (GET) /config/apps/http/servers (caddy.servers, caddy.routes) and /reverse_proxy/upstreams (caddy.upstream.requests: requests in progress, caddy.upstream.fails: failures counted by passive health checks, caddy.upstreams, caddy.upstreams.failing). Check caddy.can_connect. The admin API must never be open to the network.

MinIO

MinIO serves its metrics on /minio/v2/metrics/cluster (cluster) and /minio/v2/metrics/bucket (per bucket). Create MinIO's Prometheus token, then store the bearer_token value in a file only the agent can read:

mc admin prometheus generate myalias 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, same token
      bearer_token_file: /etc/hypha/minio.token

Without a token MinIO answers 403, unless MINIO_PROMETHEUS_AUTH_TYPE=public. In a cluster, one agent is enough (the cluster endpoint aggregates every node; server tag).

MinIO no longer publishes images or binaries of its free edition: the tested version was built from its official sources.

Mosquitto

The agent connects to the broker over MQTT 3.1.1, subscribes to $SYS/broker/# at QoS 0, reads the retained values, then disconnects: it never publishes. Give it an account that only reads $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://host:8883 over TLS (ca_file, insecure)
    username: hypha
    password: "…"

Check mosquitto.can_connect: account refused (CONNACK 4 or 5), subscription refused by the ACL, or no $SYS topic received (sys_interval 0).

Proxmox Backup Server

Create a user and an API token with the Audit role, on path /, for the user AND for the token (a token's rights are the intersection of both):

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 readonly
proxmox-backup-manager acl update / Audit --auth-id 'hypha@pbs!readonly'
proxmox-backup-manager cert info | grep Fingerprint
integrations:
  proxmox_backup:
    url: https://127.0.0.1:8007
    token_id: "hypha@pbs!readonly"
    token_secret: "…"                # value returned by generate-token
    fingerprint: "af:c8:fd:…"        # SHA-256 fingerprint of the certificate (or ca_file, or insecure: true)
    # interval: 1m
    # max_groups: 500                # backup groups followed per datastore

The subscription is never read. On every collection:

Checks: proxmox_backup.can_connect, proxmox_backup.datastore (critical: datastore in error), proxmox_backup.job (last run of every verify, prune, sync and garbage collection job; critical on failure), proxmox_backup.backup (last backup task of every group over 7 days, re-read every 5 min: critical on failure, cleared as soon as the next one succeeds).

Borg and restic

The agent runs the tool installed on the machine, without a shell and without a lock: borg --bypass-lock, restic --no-lock. A backup, prune or check in progress is never hindered or delayed by monitoring. Every repository is re-read every 15 minutes.

integrations:
  borg:
    repositories:
      - name: server
        repository: ssh://borg@backup.example/./repo
        passphrase_file: /etc/hypha/borg-server.pass       # root, mode 600 or 400
        rsh: "ssh -i /root/.ssh/borg -o BatchMode=yes"
  restic:
    repositories:
      - name: nas
        repository_file: /etc/hypha/restic-nas.repo        # address with credentials (rest:, s3:…)
        password_file: /etc/hypha/restic-nas.pass
      - name: local
        repository: /srv/restic
        password_file: /etc/hypha/restic-local.pass
    # stats: true      # repository size (borg info, restic stats), re-read every 6 h
    # interval: 15m
    # timeout: 2m
MetricMeaning
borg.last_archive.ageseconds since the start of the last complete archive
borg.archives, borg.checkpointscomplete archives, checkpoints (.checkpoint)
borg.repository.last_modified.ageseconds since the last write to the repository
borg.repository.unique_csize, .unique_size, .total_sizewith stats: true: stored size (deduplicated and compressed), deduplicated, total
restic.last_snapshot.ageseconds since the last snapshot
restic.snapshots, restic.host.last_snapshot.age (restic_host)snapshots, age of the last one per machine
restic.last_snapshot.files, .bytes, .added, .durationlast snapshot (restic 0.17 or later)
restic.repository.size, .uncompressed_size, .compression_ratiowith stats: true

Tag repository (the repository name). Checks: borg.can_connect and restic.can_connect (repository readable, otherwise critical: server unreachable, passphrase refused, badly protected file), borg.backup (warning: the last backup stopped halfway, a checkpoint newer than the last complete archive; critical: no archive) and restic.backup (critical: no snapshot).

Monitor templates

Ready-made dashboards

Dashboards › Catalogue: Pi-hole, AdGuard Home and Unbound (DNS family), Caddy (Web), MinIO (Storage), Mosquitto (Message queues), Proxmox Backup Server, Borg and restic (Backups).

Not tested

Updated: 21 November 2026