Pi-hole v6 With Unbound: Set Up Ad Blocking and Private DNS

Pi-hole v6 with Unbound gives your home network one DNS server that blocks listed ad domains and resolves the rest itself. The simplest setup is a Raspberry Pi or a small Debian-based computer running both services. Pi-hole listens to your devices on port 53; Unbound listens only on that computer at 127.0.0.1#5335.

This guide follows the standard Linux installation. Docker needs different networking because 127.0.0.1 inside a container is not the host. If you use Docker, follow Pi-hole’s container instructions and treat the upstream address separately.

Before you start

• A Raspberry Pi or Debian-based computer with a reliable connection. Ethernet is preferable for a DNS server.
• An IP address reserved for that device in your router’s DHCP settings, so it does not change after a restart.
• Access to the router’s DHCP DNS setting. If it cannot hand out a custom DNS address, you can test on one device before considering Pi-hole’s own DHCP server.
• A backup of the Pi or its Pi-hole configuration if this is an existing installation. Pi-hole v6 migrates v5 settings and a rollback is not automatic.

Make sure no other service on the Pi is already using TCP or UDP port 53. If your DNS server goes offline, devices pointed at it can lose name resolution, so put the Pi on stable power.

1. Install Pi-hole v6

Install Raspberry Pi OS Lite with Raspberry Pi Imager if you are using a Pi. Enable SSH in Imager’s customisation screen, boot with Ethernet connected, then find the Pi’s address in your router’s device list.

Connect over SSH and update the system:

ssh yourusername@pihole.local
sudo apt update && sudo apt full-upgrade -y

Pi-hole offers a one-line installer, but downloading the script first gives you a chance to inspect it. The following commands are from its official installation page:

wget -O basic-install.sh https://install.pi-hole.net
sudo bash basic-install.sh

Choose the wired interface and an upstream DNS provider for the initial installation. You will replace that provider with Unbound below. Open the admin page at the address the installer shows and set a password if one is not already in place:

pihole setpassword

2. Check that Unbound can reach DNS root servers

Before installing Unbound, check whether your ISP or router intercepts outbound DNS. If dig is missing, install it with sudo apt install dnsutils. Then run these tests on the Pi:

dig @198.41.0.4 . NS +norec +time=3
dig @198.41.0.4 . NS +norec +tcp +time=3

Pi-hole’s Unbound guide explains how to read these results. A genuine root-server answer is authoritative (aa) and does not claim recursion (ra). If both tests fail or the responses look intercepted, resolve that network problem before switching your whole home to Unbound.

3. Install and test Unbound

Install Unbound from your distribution’s package manager:

sudo apt install unbound

Create /etc/unbound/unbound.conf.d/pi-hole.conf and use Pi-hole’s recommended configuration below. It listens only on the local machine, on port 5335, so other devices cannot query Unbound directly. The Debian package normally supplies current root hints through dns-root-data.

sudo nano /etc/unbound/unbound.conf.d/pi-hole.conf

server:
    verbosity: 0

    interface: 127.0.0.1
    port: 5335
    do-ip4: yes
    do-udp: yes
    do-tcp: yes

    # May be set to no if you don't have IPv6 connectivity
    do-ip6: yes
    prefer-ip6: no

    # Only needed if you downloaded root.hints yourself
    #root-hints: "/var/lib/unbound/root.hints"

    harden-glue: yes
    harden-dnssec-stripped: yes
    use-caps-for-id: no
    edns-buffer-size: 1232
    prefetch: yes
    num-threads: 1
    so-rcvbuf: 1m

    # Ensure privacy of local IP ranges
    private-address: 192.168.0.0/16
    private-address: 169.254.0.0/16
    private-address: 172.16.0.0/12
    private-address: 10.0.0.0/8
    private-address: fd00::/8
    private-address: fe80::/10

    # No reverse queries to non-public ranges (RFC 6303 4.2)
    private-address: 192.0.2.0/24
    private-address: 198.51.100.0/24
    private-address: 203.0.113.0/24
    private-address: 255.255.255.255/32
    private-address: 2001:db8::/32

Save the file, restart Unbound and send a query to its local port:

sudo service unbound restart
dig pi-hole.net @127.0.0.1 -p 5335

Look for NOERROR and an IP address. Run the query again; the cached answer should usually be faster. Pi-hole’s guide also provides two DNSSEC tests:

dig fail01.dnssec.works @127.0.0.1 -p 5335
dig +ad dnssec.works @127.0.0.1 -p 5335

The deliberately broken fail01.dnssec.works should return SERVFAIL. The valid domain should return NOERROR with the ad flag. If your Debian or Raspberry Pi OS installation runs unbound-resolvconf.service, follow the Pi-hole guide’s service-specific fix before continuing. Otherwise that service can point the host at port 53 when Unbound is listening on 5335.

4. Point Pi-hole to Unbound

Open the Pi-hole dashboard and go to Settings > DNS. Untick the public upstream providers, enter 127.0.0.1#5335 under custom DNS servers, then select Save & Apply. Do not leave another upstream selected if you want all permitted queries to use Unbound.

Test through Pi-hole with dig pi-hole.net @127.0.0.1. If it answers, your Pi-hole-to-Unbound path is working on the server.

5. Make devices on your network use Pi-hole

In your router’s LAN or DHCP settings, set the DNS server it gives to clients to the Pi’s reserved IP address. Renew a device’s network lease or reconnect it, then check the Pi-hole dashboard for queries from that device. Some routers offer only a WAN DNS field; changing that is not the same as giving every device the Pi-hole address directly.

Try one phone or laptop first if you are unsure. Set its DNS server to the Pi’s IP, open a few sites, and check whether queries appear in Pi-hole. When that works, change the router DHCP setting. Review IPv6 DNS as well: if the router gives clients another IPv6 resolver, those requests can bypass Pi-hole.

If browsing stops working

• Check that the Pi still has the reserved IP address and that Pi-hole and Unbound are running.
• Query Unbound directly on port 5335, then query Pi-hole on port 53. This tells you which part of the chain failed.
• If Unbound cannot reach root servers over UDP or TCP, check ISP interception or router filtering.
• If only some devices bypass filtering, check their assigned DNS servers, especially IPv6 and browser-level secure DNS settings.

Unbound improves control over where DNS queries go; it does not make all browsing private or block every ad. Apps can use their own DNS or embed ads in the same domains as content. Keep Pi-hole updated and back up its settings before major changes.

• SourcePi-hole: Installation

• SourcePi-hole: Unbound setup and tests

• SourcePi-hole: Network setup after installation

• SourceRaspberry Pi: Getting started