About

Docker image for Unbound, a validating, recursive, and caching DNS resolver.

Tip

Want to be notified of new releases? Check out 🔔 Diun (Docker Image Update Notifier) project!

---

• Features
• Build locally
• Image
• Ports
• Usage
  • Docker Compose
  • Command line
• Upgrade
• Notes
  • Configuration
  • Root trust store
  • External backend DB as auxiliary cache
• Contributing
• License

Features

• Run as non-root user
• Latest Unbound release compiled from source
• Bind to unprivileged port
• Multi-platform image

Build locally

git clone https://github.com/crazy-max/docker-unbound.git
cd docker-unbound

# Build image and output to docker (default)
docker buildx bake

# Build multi-platform image
docker buildx bake image-all

Image

Registry	Image
Docker Hub	crazymax/unbound
GitHub Container Registry	ghcr.io/crazy-max/unbound

Following platforms for this image are available:

$ docker buildx imagetools inspect crazymax/unbound --format "{{json .Manifest}}" | \
  jq -r '.manifests[] | select(.platform.os != null and .platform.os != "unknown") | .platform | "\(.os)/\(.architecture)\(if .variant then "/" + .variant else "" end)"'

linux/amd64
linux/arm/v6
linux/arm/v7
linux/arm64
linux/ppc64le
linux/s390x

Volumes

• /config: Additional configuration files

Ports

• 5053/tcp 5053/udp: DNS listening port

Usage

Docker Compose

Docker compose is the recommended way to run this image. You can use the following docker compose template, then run the container:

docker compose up -d
docker compose logs -f

Command line

You can also use the following minimal command:

docker run -d -p 5053:5053 --name unbound crazymax/unbound

Upgrade

Recreate the container whenever I push an update:

docker compose pull
docker compose up -d

Notes

Configuration

When Unbound is started the main configuration /etc/unbound/unbound.conf is imported.

If you want to override settings from the main configuration you have to create config files (with .conf extension) in /config folder.

For example, you can set up forwarding queries to the appropriate public DNS server for queries that cannot be answered by this server using a new configuration named /config/forward-records.conf:

forward-zone:
  name: "."
  forward-tls-upstream: yes

  # cloudflare-dns.com
  forward-addr: 1.1.1.1@853
  forward-addr: 1.0.0.1@853
  #forward-addr: 2606:4700:4700::1111@853
  #forward-addr: 2606:4700:4700::1001@853

A complete documentation about Ubound configuration can be found on NLnet Labs website: https://nlnetlabs.nl/documentation/unbound/unbound.conf/

Warning

Container has to be restarted to propagate changes

Root trust store

This image already embeds a root trust anchor to perform DNSSEC validation.

If you want to generate a new key, you can use unbound-anchor which is available in this image:

docker run -t --rm --entrypoint "" -v "$(pwd):/trust-anchor" crazymax/unbound:latest \
  unbound-anchor -v -a "/trust-anchor/root.key"

If you want to use your own root trust anchor, you can create a new config file called for example /config/00-trust-anchor.conf:

  auto-trust-anchor-file: "/root.key"

Note

See documentation for more info about auto-trust-anchor-file setting.

And bind mount the key:

services:
  unbound:
    image: crazymax/unbound
    container_name: unbound
    ports:
      - target: 5053
        published: 5053
        protocol: tcp
      - target: 5053
        published: 5053
        protocol: udp
    volumes:
      - "./config:/config"
      - "./root.key:/root.key"
    restart: always

External backend DB as auxiliary cache

The cache DB module is already configured in the module-config directive and compiled into the daemon.

You just need to create a new Redis service with persistent storage enabled in your compose file along the Unbound one.

services:
  redis:
    image: redis:6-alpine
    container_name: unbound-redis
    command: redis-server --save 60 1
    volumes:
      - "./redis:/data"
    restart: always

  unbound:
    image: crazymax/unbound
    container_name: unbound
    depends_on:
      - redis
    ports:
      - target: 5053
        published: 5053
        protocol: tcp
      - target: 5053
        published: 5053
        protocol: udp
    volumes:
      - "./config:/config:ro"
    restart: always

And declare the backend configuration to use this Redis instance in /config like /config/cachedb.conf:

cachedb:
  backend: "redis"
  secret-seed: "default"
  redis-server-host: redis
  redis-server-port: 6379

Contributing

Want to contribute? Awesome! The most basic way to show your support is to star the project, or to raise issues. You can also support this project by becoming a sponsor on GitHub or by making a PayPal donation to ensure this journey continues indefinitely!

Thanks again for your support, it is much appreciated! 🙏

License

MIT. See LICENSE for more details.