# Pi-hole + Unbound DNS Stack

> Network-wide ad blocking with Pi-hole and recursive DNS with Unbound.

- Category: Home Lab & Self-Hosting
- Difficulty: beginner
- Components: pihole, unbound, prometheus, grafana
- Tags: pihole, unbound, dns, adblock, privacy
- Source: https://docker.recipes/homelab/pi-hole-unbound

## Overview

Pi-hole is a network-level DNS sinkhole that blocks advertisements and trackers at the network infrastructure level, protecting all connected devices without requiring client-side software. Originally developed as a Raspberry Pi project, Pi-hole has evolved into a comprehensive DNS filtering solution that intercepts DNS queries and blocks requests to known advertising and malicious domains before they reach your devices. This approach provides superior performance compared to browser-based ad blockers since blocked content never gets downloaded.

This stack combines Pi-hole with Unbound recursive DNS resolver to create a completely self-contained, privacy-focused DNS infrastructure. Unbound eliminates the need for upstream DNS providers like Google or Cloudflare by performing recursive DNS lookups directly from authoritative nameservers. The integration includes Pi-hole Exporter for metrics collection, Prometheus for time-series data storage, and Grafana for visualization, providing comprehensive monitoring of DNS query patterns, blocking statistics, and resolver performance.

Home network administrators and privacy-conscious users will find this stack particularly valuable for reducing bandwidth usage, improving browsing speed, and maintaining complete control over DNS resolution. The combination delivers enterprise-grade DNS filtering and monitoring capabilities while ensuring that DNS queries never leave your network infrastructure, maximizing privacy and reducing dependency on external DNS services.

## Features

- Network-wide ad and tracker blocking without client-side configuration
- Recursive DNS resolution through Unbound eliminating upstream DNS dependencies
- Real-time DNS query logging and statistics through Pi-hole web interface
- Custom blocklist management with regex filtering capabilities
- Prometheus metrics collection for DNS query patterns and blocking statistics
- Grafana dashboards for visualizing DNS performance and threat intelligence
- Group-based device management for different filtering policies
- DHCP server integration for automatic network device configuration

## Use cases

- Home network ad blocking for all connected devices including smart TVs and IoT devices
- Privacy-focused DNS infrastructure avoiding reliance on commercial DNS providers
- Parental controls with custom blocklists and time-based filtering
- Network security monitoring to identify malware communication attempts
- Bandwidth optimization by blocking resource-heavy advertisements and tracking scripts
- Small office DNS filtering with user group policies and access logging
- Home lab DNS analytics and performance monitoring with historical data

## Prerequisites

- Minimum 1GB RAM recommended for full stack with monitoring components
- Static IP address for the Docker host to serve as network DNS server
- Port 53 (TCP/UDP) available for DNS queries and port 80 for Pi-hole admin interface
- Network router configuration access to change DHCP DNS settings
- Basic understanding of DNS concepts and network configuration
- Unbound configuration file (unbound.conf) for recursive resolver settings

## docker-compose.yml

```yaml
services:
  pihole:
    image: pihole/pihole:latest
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80"
    environment:
      - TZ=UTC
      - WEBPASSWORD=${PIHOLE_PASSWORD}
      - PIHOLE_DNS_=unbound#5335
    volumes:
      - pihole_config:/etc/pihole
      - pihole_dnsmasq:/etc/dnsmasq.d
    depends_on:
      - unbound
    cap_add:
      - NET_ADMIN
    networks:
      pihole_net:
        ipv4_address: 172.20.0.2

  unbound:
    image: mvance/unbound:latest
    volumes:
      - ./unbound.conf:/opt/unbound/etc/unbound/unbound.conf:ro
    networks:
      pihole_net:
        ipv4_address: 172.20.0.3

  pihole-exporter:
    image: ekofr/pihole-exporter:latest
    environment:
      - PIHOLE_HOSTNAME=pihole
      - PIHOLE_PASSWORD=${PIHOLE_PASSWORD}
    ports:
      - "9617:9617"
    depends_on:
      - pihole
    networks:
      - pihole_net

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    networks:
      - pihole_net

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
    volumes:
      - grafana_data:/var/lib/grafana
    networks:
      - pihole_net

volumes:
  pihole_config:
  pihole_dnsmasq:
  prometheus_data:
  grafana_data:

networks:
  pihole_net:
    ipam:
      config:
        - subnet: 172.20.0.0/24
```

## .env

```bash
# Pi-hole + Unbound
PIHOLE_PASSWORD=secure_pihole_password
GRAFANA_PASSWORD=secure_grafana_password

# Pi-hole Admin at http://localhost/admin
# DNS at localhost:53
```

## Usage notes

- Pi-hole Admin at http://localhost/admin
- Set device DNS to Pi-hole IP
- Unbound provides recursive DNS
- No upstream DNS provider needed
- Privacy-focused DNS resolution

## Troubleshooting

- Pi-hole admin interface shows 'DNS resolution is currently failing': Check that Unbound container is running and accessible on port 5335
- Devices not using Pi-hole for DNS queries: Verify router DHCP settings point to Pi-hole IP address or configure device DNS manually
- Unbound failing to start with permission errors: Ensure unbound.conf file has correct read permissions and valid configuration syntax
- High memory usage from Prometheus: Adjust retention policies in prometheus.yml or increase Docker host memory allocation
- Grafana dashboards showing no data: Verify pihole-exporter is collecting metrics and Prometheus is scraping the exporter endpoint
- DNS queries timing out intermittently: Check Docker network configuration and ensure containers have static IP addresses in pihole_net network

