Pi-hole Integration

Overview

If your UniFi gateway does not forward DNS query logs (see DNS Logging), Insights Plus can poll a Pi-hole instance directly over its REST API and import every query into the same log stream as the rest of your network data. Queries are mapped to the standard log schema, enriched with GeoIP and threat intelligence, and appear alongside firewall and DHCP events in the dashboard.

Prerequisites

• A reachable Pi-hole v6 instance with its web admin interface accessible from the Insights Plus container
• The Pi-hole admin password (used to obtain a session ID via /api/auth)
• Pi-hole privacy level set to “Show everything and record everything” (level 0) - any higher level hides domains or client IPs and makes the data unusable. Configure this under Pi-hole Settings > Privacy > Query Anonymization.

Setup via the UI

1. Open Settings > Integrations > Pi-hole in the Insights Plus web UI.
2. Enter your Pi-hole URL. Include the scheme and port, no trailing slash. Both IP addresses and hostnames are supported, including local domains resolved by your own network — for example http://192.0.2.10:80, http://pihole.mydomain.local, or https://pihole.example.net.
3. Enter the Pi-hole admin password. It is encrypted at rest using the same key as your other API credentials.
4. Choose a Poll Interval: 15s for large networks (50+ devices), 30-60s for most homes, 2-5m for light use.
5. Choose an Enrichment option (None, GeoIP only, Threat only, or Both). This controls whether resolved query IPs are enriched with GeoIP and AbuseIPDB threat data.
6. Click Test Connection. On success, the version is displayed and the Enable toggle becomes available. Save to start polling.

The status card shows Active once the first poll completes successfully, along with the last poll timestamp.

Setup via Environment Variables

Pi-hole can also be configured headlessly. When both PIHOLE_HOST and PIHOLE_PASSWORD are set, the integration auto-enables on first start.

How It Works

• Authentication - The poller posts the password to /api/auth to obtain a session ID, then renews it automatically before expiry.
• Polling - /api/queries is fetched every poll interval. The first poll only imports the last 5 minutes; subsequent polls track the highest query ID seen and import only newer records.
• Mapping - Each Pi-hole query becomes a standard DNS log entry with action allow or block based on Pi-hole's status (FORWARDED, CACHE, GRAVITY, REGEX, etc).
• DNS Resolution- For non-blocked A/AAAA queries, the poller resolves the answer against Pi-hole's own DNS port (53) so enrichment matches what clients actually received. Results are cached for 5 minutes.
• Enrichment - Resolved public IPs flow through the same GeoIP and AbuseIPDB pipeline as the rest of your logs.

Troubleshooting

• “Pi-hole vX.X is not supported” - Only Pi-hole v6 is supported. Upgrade your Pi-hole instance.
• “Privacy level must be set to...” - Set Pi-hole Settings > Privacy > Query Anonymization to the first option (level 0). Anything higher hides domains or client IPs.
• Status shows “Offline” after enabling - Confirm the URL is reachable from inside the Insights Plus container (try docker exec + curl). Check the container logs for pihole-poller messages.
• Auth rate-limited (HTTP 429) - Pi-hole limits concurrent sessions. The poller backs off automatically; avoid logging in to the Pi-hole admin UI in multiple tabs at once.
• “Returned queries at fetch limit” warning - Your network is generating more than 10,000 queries per poll interval. Reduce the poll interval to keep up.