bfren/unbound repository overview

⁠Unbound

Docker Hub⁠ - Quay.io⁠ - bfren ecosystem⁠

⁠Introduction

Unbound⁠ is a recursive DNS resolver: instead of sending your lookups to a public DNS provider, it asks the root servers and each domain's own name servers directly, and can check the answers with DNSSEC.

It is built on Alpine + S6⁠, with Unbound from Alpine's packages, and is configured with environment variables. It works well as the upstream resolver for Pi-hole⁠ - see the example compose files in this repository.

⁠Quickstart

services:
  unbound:
    image: quay.io/bfren/unbound:3.1
    restart: unless-stopped
    ports:
      - "127.0.0.1:53:53/tcp"
      - "127.0.0.1:53:53/udp"
    environment:
      - BF_UNBOUND_ENABLE_DNSSEC=1

Run docker compose up -d, then test it from the host:

dig example.com @127.0.0.1

docker-compose.yml in this repository runs Pi-hole with two Unbound containers, and docker-compose-with-proxy.yml puts Pi-hole's admin site behind a proxy. Copy .env alongside them and change the values.

⁠Features

• 🔎 Recursive resolver - no third-party DNS provider sees your lookups
• 🔐 DNSSEC validation, with the root trust anchor kept up to date
• ⚙️ About 50 Unbound settings available as environment variables
• 🛡️ Optional protection against DNS rebinding (private addresses)
• ✅ Configuration checked before Unbound starts
• 🩺 Health check that resolves a real domain
• 🧪 Built-in tests

⁠Tags

Images are published to Docker Hub (bfren/unbound) and Quay.io (quay.io/bfren/unbound) for linux/amd64, linux/arm/v7 and linux/arm64, with Unbound 1.25.2 on Alpine 3.24.

⁠Configuration

⁠Ports

⁠Environment Variables

Each of these sets the Unbound option of the same name - see the unbound.conf manual⁠ for what they do:

See Alpine + S6⁠ for BF_DEBUG, BF_TZ and the other base image variables.

⁠How It Works

On every start /etc/unbound/unbound.conf is generated from the environment variables. Unbound listens on port 53 on every IPv4 address in the container, and answers anyone who can reach it - so only publish the port where you mean to.

Before Unbound starts:

• with BF_UNBOUND_ENABLE_DNSSEC=1, unbound-anchor downloads or updates the root trust anchor (/etc/unbound/root.key)
• unbound-checkconf checks the configuration - if it is invalid, Unbound doesn't start, and the error is in the log

Then Unbound runs under S6 as the unbound user. The container stops if it crashes. The root hints (the addresses of the root servers) are downloaded when the image is built.

The health check (every 30 seconds) looks up cloudflare.com using Unbound itself, so it fails if Unbound can't reach the internet.

⁠Testing

./test.nu   # builds the image and runs /test
./run.sh    # builds the image and opens a shell, with DNSSEC on and Unbound on 127.0.0.1:5353/udp

/test runs this image's tests alongside the base images' tests: the generated unbound.conf (with and without DNSSEC, defaults, settings and private addresses), the paths used, and the installed Unbound version.

⁠Troubleshooting

⁠The container keeps restarting

Unbound's configuration check failed, or the trust anchor couldn't be downloaded. Check docker logs <container> - a mistyped value in a BF_UNBOUND_* variable is the usual cause.

⁠Lookups fail with SERVFAIL

With DNSSEC on, SERVFAIL usually means an answer failed validation - often because the container's clock is wrong, or the domain's DNSSEC is broken. Try the lookup with +cd (checking disabled), e.g. dig example.com @127.0.0.1 +cd, to see which.

⁠Port 53 is already in use on the host

On many Linux systems systemd-resolved uses port 53. Publish Unbound on a specific address (e.g. "192.168.1.10:53:53/udp"), or use it only from other containers.

⁠FAQs

⁠Why run two Unbound containers in the example?

So DNS keeps working while one restarts or updates. Pin the second one to an older image version (UNBOUND_PIN in .env) and update it separately.

⁠Can I add my own Unbound settings?

unbound.conf includes every *.conf file in /etc/unbound/unbound.conf.d, so mount your own files there.

⁠Licence

⁠Copyright