pihole-unbound

Level up your network with cutting-edge tech. This Docker container effortlessly combines Pi-Hole and Unbound, giving you the ultimate privacy and performance combo in a single package. It's the future of network management, available today.

Note

Development for the development tag is currently ongoing, there could be some bugs. The development tag uses Alpine Linux. If you're familiar with Alpine, we encourage you to check out the Dockerfile-Dev-V6 file. Your contributions are highly appreciated!

Supported Architectures

We utilise the docker buildx for multi-platform awareness. More information is available from docker here.

Simply pulling rlabinc/pihole-unbound:latest should retrieve the correct image for your arch, but you can also pull specific arch images via --platform.

The architectures supported by this image are:

Architecture	Available	Platform
amd64	✅	linux/amd64
arm64	✅	linux/arm64
armhf	✅	linux/arm/v7
armel	✅	linux/arm/v6

Usage

Docker run

Here are the commands you'll need:

docker run -d \
  --name=pihole-unbound \
  -e TZ=Europe/London `#optional` \
  -p 53:53/tcp -p 53:53/udp \
  -p 80:80/tcp `#Pi-hole web interface port` \
  -e WEBPASSWORD='qwerty123' `#better to use single quotes` \
  --restart=always \
  rlabinc/pihole-unbound:latest

Docker Compose

To deploy this project using Docker Compose, you can use the following example docker-compose.yml:

version: '3'

services:
  pihole-unbound:
    image: rlabinc/pihole-unbound:latest
    container_name: pihole-unbound
    environment:
      - TZ=Europe/London # Adjust timezone as needed
      - WEBPASSWORD=qwerty123 # Set a secure password
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp" #Pi-hole web interface port
    restart: always

This example configuration will run Pi-hole with Unbound, listening on port 53 for DNS queries and port 80 for the web interface. Make sure to adjust the environment variables, password, and timezone according to your setup.

To start the container, use:

docker-compose up -d

To stop the container, use:

docker-compose down

Tip

Mikrotik users: Facing cp: cannot create special file, the solution was letting RouterOS create the mounted volume itself, and not manually creating a "directory" beforehand. As result, the mount appears as "container store" (so not a "directory"), accessible via SFTP (and not via Winbox/WebFig) for pushing custom Unbound config. - @riccardo1991

Docker Tags

The Docker tags supported by this image are:

Tag	Type	Status	Development	Description
latest	Stable		✅	Always latest release
2024.02.2-1.19.3	Stable		✅	Date-based release [Pi-hole Version-Unbound Version]
dev	Beta		❌	[DEPRECATED] Similar to latest, but for the development branch (pushed occasionally)
development	Beta		✅	Upcoming Alpine based v6 release
test	Test	❌	🔬	Testing purpose only

Note

The development has been entirely redesigned from the ground up and contains many breaking changes, for more info regarding development visit here.

Installing on Ubuntu

Modern releases of Ubuntu (17.10+) include systemd-resolved which is configured by default to implement a caching DNS stub resolver. This will prevent pi-hole from listening on port 53. The stub resolver should be disabled with: sudo sed -r -i.orig 's/#?DNSStubListener=yes/DNSStubListener=no/g' /etc/systemd/resolved.conf

This will not change the nameserver settings, which point to the stub resolver thus preventing DNS resolution. Change the /etc/resolv.conf symlink to point to /run/systemd/resolve/resolv.conf, which is automatically updated to follow the system's netplan: sudo sh -c 'rm /etc/resolv.conf && ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf' After making these changes, you should restart systemd-resolved using systemctl restart systemd-resolved

Once pi-hole is installed, you'll want to configure your clients to use it (see here). If you used the symlink above, your docker host will either use whatever is served by DHCP, or whatever static setting you've configured. If you want to explicitly set your docker host's nameservers you can edit the netplan(s) found at /etc/netplan, then run sudo netplan apply. Example netplan:

network:
    ethernets:
        ens160:
            dhcp4: true
            dhcp4-overrides:
                use-dns: false
            nameservers:
                addresses: [127.0.0.1]
    version: 2

Note that it is also possible to disable systemd-resolved entirely. However, this can cause problems with name resolution in vpns (see bug report). It also disables the functionality of netplan since systemd-resolved is used as the default renderer (see man netplan). If you choose to disable the service, you will need to manually set the nameservers, for example by creating a new /etc/resolv.conf.

Users of older Ubuntu releases (circa 17.04) will need to disable dnsmasq.

Parameters

Container images are configured using parameters passed at runtime (such as those above).

Parameter	Function	development-v6 Only
-e TZ=Europe/London	Specify a timezone to use ex Europe/London.	-e TZ=Europe/London
-p 53:53/tcp -p 53:53/udp	Default DNS port to use.	-p 53:53/tcp -p 53:53/udp
-p 80:80/tcp	Specify Pi-hole web interface port.	-p 80:80/tcp
-e WEBPASSWORD='qwerty123'	Specify Pi-hole web interface password. It is better to use single quotes.	-e FTLCONF_webserver_api_password='qwerty123'
--restart=always	To make sure "It's Always DNS" does not happen.	--restart=always
-v /opt/unbound/etc/unbound	Your customized Unbound configuration unbound.conf location.	-v /opt/unbound/etc/unbound

This Docker container supports all Pi-hole official Docker container environment variables available here.

Quick Links

• Telegram Support
• Pihole Docker Github Repository
• Unbound Github Repository
• Pi-hole Unbound Github Repository
• Pi-hole Unbound Docker Hub

Acknowledgements

The code in this image is heavily influenced by MatthewVance's unbound-docker with the help of chriscrowe's docker-pihole-unbound server Docker image configs, However, the upstream projects most certainly also deserve credit for making this all possible.

• pi-hole.
• NLnetLabs.
• MatthewVance.
• chriscrowe.
• madnuttah.
• The many other devs who got me inspired!

Warning

I'm not responsible if your internet goes down using this Docker container. Use at your own risk.