Docker - Unbound Container Setup with Pi-hole

Here I describe my setup of the Unbound docker container.

I run this Docker container on a Ubuntu VM that runs via [[ Proxmox VE ]]. I perform the following on the CLI.

Docker Network

To allow Unbound to communicate with Pi-hole, a network must be configured. See the setup of the Pi-hole container for this.

Container Setup

Run the Docker pull command:

docker pull klutchell/unbound

Within my home folder I have created a Docker folder where I create a subfolder for each container:

cd ~
mkdir -p docker/unbound
cd docker/unbound

First download the root.hints:

sudo wget -O root.hints

This file is not often changed but you can have this file automatically updated every month at 8:00 pm as follows:

sudo crontab -e

And add:

0 20 1 * * wget -O /home/USER/docker/unbound/root.hints

Replace USER with your username.

Exit Nano (CTRL-X) and save the changes.

Use the Nano text editor to create the unbound.conf:

sudo nano unbound.conf

Add the following:

 ## To listen on all interfaces use:
 interface: [email protected]

 do-ip4: yes
 do-udp: yes
 do-tcp: yes

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

 # You want to leave this to no unless you have *native* IPv6. With 6to4 and
 # Terredo tunnels your web browser should favor IPv4 for the same reasons
 prefer-ip6: no

 do-daemonize: no

 access-control: allow
 access-control: allow
 access-control: allow
 access-control: allow

 logfile: ""

 # If no logfile is specified, syslog is used
 # logfile: "/var/log/unbound/unbound.log"
 verbosity: 0

 include: /opt/unbound/etc/unbound/a-records.conf

 # Use this only when you downloaded the list of primary root servers!
 root-hints: "/opt/unbound/etc/unbound/root.hints"

 # Trust glue only if it is within the servers authority
 harden-glue: yes

 # Require DNSSEC data for trust-anchored zones, if such data is absent, the zone becomes BOGUS
 harden-dnssec-stripped: yes

 # Don't use Capitalization randomization as it known to cause DNSSEC issues sometimes
 # see for further details
 use-caps-for-id: no

 # Reduce EDNS reassembly buffer size.
 # Suggested by the unbound man page to reduce fragmentation reassembly problems
 edns-buffer-size: 1472

 # TTL bounds for cache
 cache-min-ttl: 3600
 cache-max-ttl: 86400

 # Perform prefetching of close to expired message cache entries
 # This only applies to domains that have been frequently queried
 prefetch: yes

 # One thread should be sufficient, can be increased on beefy machines
 num-threads: 1

 # Ensure kernel buffer is large enough to not loose messages in traffic spikes
 #so-rcvbuf: 1m
 # Ensure privacy of local IP ranges
 private-address: fd00::/8
 private-address: fe80::/10

Exit Nano (CTRL-X) and save the changes.

Also create a-records.conf:

sudo nano a-records.conf

And add the following (every line is commented out):

# A Record
#local-data: "somecomputer.local. A"
#local-data: "laptop.local. A"

# PTR Record
#local-data-ptr: " somecomputer.local."
#local-data-ptr: " laptop.local."

Exit Nano (CTRL-X) and save the changes so the file is created.

Create a shell script:

sudo nano

With this shell script we are going to create the container. Copy the following into

docker run -d \
 --name unbound \
 --hostname=unbound \
 --network=dns-net \
 --ip= \
 -p 5053:5053/tcp \
 -p 5053:5053/udp \
 -v $PWD/:/opt/unbound/etc/unbound \
 --restart=unless-stopped \

If necessary, adjust the following:

-p 5053:5053/tcp and -p 5053:5053/udp
This is the port used by Pi-hole as part of the custom upstream DNS server. Make sure the ports are available. Check this with netstat. When port 5053 is already in use you can change this port. Do not forget to also change the interface in the configuration file unbound.conf

This is the IP address used by Pi-hole as custom upstream DNS server

Exit Nano (CTRL-X) and save the changes.

Now create the container:

sudo sh

Check if the container is running properly.

Using Unbound

Unbound can be tested with dig:

dig @127.0.01 -p 5053

When the dig command is not found just install dnsutils:

sudo apt-get install dnsutils

Now make sure Unbound is configured as Upstream DNS server in Pi-hole. Inside the Pi-hole UI go to Settings > DNS. Uncheck all Upstream DNS Servers and add as Custom 1 (IPv4).

See also my notes about updating containers with Portainer or via the CLI. With Synology’s Docker Application, updating a container is also very easy.

Read other notes


    No comments found for this note.

    Join the discussion for this note on this ticket. Comments appear on this page instantly.


    Notes mentioning this note

    Notes Graph