Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/damianiglesias/pihole-ubuntu-deploy/llms.txt

Use this file to discover all available pages before exploring further.

Unbound is an optional recursive DNS resolver that lets Pi-hole resolve DNS queries directly from the root servers, eliminating reliance on upstream providers like Google (8.8.8.8) or Cloudflare (1.1.1.1). When enabled, Pi-hole forwards all DNS queries to Unbound on 127.0.0.1#5335, which then walks the DNS hierarchy from the root down to the authoritative nameserver for each domain — no third-party involved.
Unbound is included in the installer but is currently experimental and may not work correctly in all environments. The author notes they are working on a fix in future versions.

​
Installation

During the deploy.sh interactive setup you will be prompted at Step 4.5: 
Step 4.5: Unbound Recursive DNS
   Install Unbound? [y/n]:
Type y and press Enter. The script will:
  1. Install the unbound package via apt.
  2. Download the latest root hints file from internic.net to /var/lib/unbound/root.hints.
  3. Write the configuration file to /etc/unbound/unbound.conf.d/pi-hole.conf.
  4. Restart the unbound service.

​
Generated Configuration

The installer writes the following configuration to /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
    do-ip6: no
    prefer-ip6: no
    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
    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

​
Key Configuration Options

OptionValueDescription
verbosity0Silent logging. Increase to 1–5 for debug output.
port5335Listens on a non-standard port to avoid conflict with Pi-hole on port 53.
root-hints/var/lib/unbound/root.hintsPath to the root nameserver list downloaded from internic.net.
harden-glueyesRequires that glue records are within the authority of the zone.
harden-dnssec-strippedyesRejects unsigned DNSSEC answers where signing was expected.
edns-buffer-size1232Safe buffer size (bytes) that avoids IP fragmentation on most networks.
prefetchyesPre-fetches popular cache entries before they expire, reducing latency.
private-addressMultiple RFC-1918 rangesPrevents DNS rebinding attacks by blocking private IPs in public DNS responses.

​
Pointing Pi-hole at Unbound

After Unbound is installed, you must tell Pi-hole to use it as the upstream resolver.
1

Log into the Pi-hole web interface

Navigate to http://<server-ip>/admin in your browser and sign in with your admin password.
2

Go to Settings → DNS

In the left sidebar, click Settings, then select the DNS tab.
3

Uncheck any existing upstream providers

Remove any checked upstream providers such as Google (8.8.8.8) or Cloudflare (1.1.1.1). Leaving them enabled defeats the purpose of Unbound.
4

Add Unbound as a custom upstream

Under Custom 1 (IPv4), check the box and enter:
127.0.0.1#5335
5

Save settings

Scroll to the bottom of the page and click Save. Pi-hole will now route all DNS queries through Unbound.

​
Standalone Installation

If you skipped Unbound during deploy.sh and want to install it separately, run the following commands: 
# Install Unbound
sudo apt-get install unbound -y

# Download root hints
sudo wget -O /var/lib/unbound/root.hints https://www.internic.net/domain/named.root
sudo chown unbound:unbound /var/lib/unbound/root.hints

# Restart the service
sudo systemctl restart unbound
Then write the configuration file shown above to /etc/unbound/unbound.conf.d/pi-hole.conf and configure Pi-hole’s DNS settings to point to 127.0.0.1#5335 as described in the steps above.

Build docs developers (and LLMs) love

Get started for freeTalk to us