Unbound Dashboard

Unbound Dashboard Skill

This skill provides expert knowledge for setting up a comprehensive dashboard for Unbound DNS using the Prometheus + Grafana + Loki stack. It is based on the ar51an/unbound-dashboard repository.

Capabilities

• Installation Guide: Step-by-step instructions for Grafana, Prometheus, and Loki on ARM64 (Raspberry Pi), easily adaptable to other architectures.
• Unbound Exporter: Configuration and usage of the unbound-exporter to collect metrics.
• Log Aggregation: Setting up Loki and Promtail to ingest and query Unbound logs.
• Dashboard Management: Importing and configuring the Grafana dashboard.
• Troubleshooting: Tips for common issues and optimizations.

Prerequisite Stack

• Grafana: Visualisation platform.
• Prometheus: Time-series database for metrics.
• Loki: Log aggregation system.
• Unbound: The DNS resolver itself.
• Go: (Optional) if building the exporter from source.

Installation Steps

1. Grafana Setup

Download & Install (ARM64 example):

wget https://dl.grafana.com/oss/release/grafana_11.1.0_arm64.deb
sudo apt install musl
sudo dpkg -i grafana_11.1.0_arm64.deb

Configuration:

• Access UI at http://<IP>:3000 (Default: admin/admin).
• A tweaked grafana.ini is available in the release for reduced memory footprint.

Service Management:

sudo systemctl daemon-reload
sudo systemctl enable grafana-server
sudo systemctl start grafana-server

2. Prometheus Setup

Install:

sudo apt install prometheus

Configuration (prometheus.yml):

• Configure to scrape unbound-exporter.
• Disable default node-exporter if not needed to save resources.
• Scrape interval recommendation: 5m.

Clean up:

• Remove prometheus-node-exporter if not used.

3. Unbound Exporter Setup

The exporter collects statistics from Unbound. Binary available in releases.

Unbound Config (/etc/unbound/unbound.conf):

server:
    extended-statistics: yes

remote-control:
    control-interface: "/var/run/unbound.sock"
    control-use-cert: no

Install Exporter:

1. Copy binary to /usr/local/bin/unbound-exporter.
2. Make executable: chmod +x /usr/local/bin/unbound-exporter.
3. Setup systemd service (prometheus-unbound-exporter.service).

4. Loki & Promtail Setup (Logs)

Install:

# Download .deb packages from Grafana releases
sudo dpkg -i loki_<version>_arm64.deb
sudo dpkg -i promtail_<version>_arm64.deb

Unbound Logging Config:

server:
    log-replies: yes
    log-tag-queryreply: yes
    log-local-actions: yes
    logfile: /var/log/unbound/unbound.log
    verbosity: 0

Ensure /var/log/unbound exists and is writable by unbound user.

Loki/Promtail Config:

• Use the optimized config.yml provided in the repository release for better performance with Unbound logs.

5. Dashboard Import

1. Add Data Sources in Grafana:
   • Prometheus: http://localhost:9090
   • Loki: http://localhost:3100 (Max lines: 100000)
2. Import JSON:
   • Upload unbound-dashboard.json from the release.
   • Select the Prometheus and Loki data sources.

Panels & Metrics

• Lookup Avg: Average recursive query time (uncached).
• Req Max/Avg: Recursive processing request list size.
• Recursion Time: Graph of recursion times (Avg & Median).
• Client Requests: Bar graphs of requests per client.
• Top Client Queries: Table of domains requested by each client.
• Live Blocked: Real-time blocked domains table.

Tips

• Theme: You can switch Grafana theme between Dark/Light in User Preferences.
• Map IPs to Hostnames: Use Grafana's Overrides -> Value mappings in panels to show hostnames instead of IPs.
• Reset Metrics: You can clear Prometheus time series using the Admin API if enabled.

References

• Source Repo: https://github.com/ar51an/unbound-dashboard
• Dashboard Release: https://github.com/ar51an/unbound-dashboard/releases