crazy-max / docker-unbound

Unbound Docker image

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 run --rm mplatform/mquery crazymax/unbound:latest
Image: crazymax/unbound:latest
 * Manifest List: Yes
 * Supported platforms:
   - 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.

docker-unbound's Issues

handshake failed

Behaviour

Steps to reproduce this issue

1. start docker compose from the last version

Expected behaviour

unbound        | [1670938176] unbound[1:0] info: failed to prime trust anchor -- could not fetch DNSKEY rrset . DNSKEY IN
unbound        | [1670938190] unbound[1:0] error: ssl handshake failed crypto error:1416F086:SSL routines:tls_process_server_certificate:certificate verify failed
unbound        | [1670938190] unbound[1:0] notice: ssl handshake failed 1.0.0.1 port 853
unbound        | [1670938190] unbound[1:0] error: ssl handshake failed crypto error:1416F086:SSL routines:tls_process_server_certificate:certificate verify failed
unbound        | [1670938190] unbound[1:0] notice: ssl handshake failed 1.0.0.1 port 853
unbound        | [1670938190] unbound[1:0] error: ssl handshake failed crypto error:1416F086:SSL routines:tls_process_server_certificate:certificate verify failed
unbound        | [1670938190] unbound[1:0] notice: ssl handshake failed 1.1.1.1 port 853
unbound        | [1670938190] unbound[1:0] error: ssl handshake failed crypto error:1416F086:SSL routines:tls_process_server_certificate:certificate verify failed
unbound        | [1670938190] unbound[1:0] notice: ssl handshake failed 1.1.1.1 port 853

Actual behaviour

Tell me what happens instead

Configuration

• Docker version (type docker --version) : Docker version 20.10.12, build 20.10.12-0ubuntu2~20.04.1
• Docker compose version if applicable (type docker-compose --version) : Docker Compose version v2.14.0
• Platform (Debian 9, Ubuntu 18.04, ...) : ubuntu 20.04
• System info (type uname -a) : Linux adguard 5.15.0-56-generic #62~20.04.1-Ubuntu SMP Tue Nov 22 21:24:20 UTC 2022 x86_64 x86_64 x86_64 GNU/Linux
• Include all necessary configuration files : docker-compose.yml, .env, ...

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

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

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

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

Docker info

Client:
 Context:    default
 Debug Mode: false

Server:
 Containers: 4
  Running: 0
  Paused: 0
  Stopped: 4
 Images: 4
 Server Version: 20.10.12
 Storage Driver: overlay2
  Backing Filesystem: extfs
  Supports d_type: true
  Native Overlay Diff: true
  userxattr: false
 Logging Driver: json-file
 Cgroup Driver: cgroupfs
 Cgroup Version: 1
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local logentries splunk syslog
 Swarm: inactive
 Runtimes: io.containerd.runc.v2 io.containerd.runtime.v1.linux runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version:
 runc version:
 init version:
 Security Options:
  apparmor
  seccomp
   Profile: default
 Kernel Version: 5.15.0-56-generic
 Operating System: Ubuntu 20.04.3 LTS
 OSType: linux
 Architecture: x86_64
 CPUs: 4
 Total Memory: 3.719GiB
 Name: adguard
 ID: 3KH4:W2Y7:XGRJ:B5N2:7XY6:N3Z3:7SWI:Z5RT:YUJP:76XY:ENE2:ZLGQ
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 Registry: https://index.docker.io/v1/
 Labels:
 Experimental: false
 Insecure Registries:
  127.0.0.0/8
 Live Restore Enabled: false


### Logs

Container logs (set LOG_LEVEL to debug if applicable)

CacheDB compile

Hi Crazy-Max. First of all THANK YOU for an amazing image. This is the only docker image I could get working properly :).

QQ: Would you be able to include the cachedb option into a future release?

The Cache DB module must be configured in the module-config: "validator
cachedb iterator" directive and be compiled into the daemon with --en-
able-cachedb. If this module is enabled and configured, the specified
backend database works as a second level cache: When Unbound cannot
find an answer to a query in its built-in in-memory cache, it consults
the specified backend. If it finds a valid answer in the backend, Un-
bound uses it to respond to the query without performing iterative DNS
resolution. If Unbound cannot even find an answer in the backend, it
resolves the query as usual, and stores the answer in the backend.

The main reason for this is it allows you to keep a persistent DB that survives reboots / image updates and means you don’t have to rebuild it all again.

Thanks,

Lammi

Please update to latest version - Unbound 1.17.0

Hi! The Docker image is not updated to the latest released unbound version. It'd be great if you could merge the cache-db branch to the master. I've been using that branch without any issues for some time.

Issue with latest update

Hi` Crazy-Max! Thanks for pushing the redis support. My image updated today but I’m getting the following error:

Error loading shared library libhiredis.so. 1.0.0: No such file or directory (needed by /us/sbin/unbound-checkconf)’
Error relocating /us/sbin/unbound -checkconf freeReolvobiect: symbol not found
Error relocating us sin unbound-checkcont: redisconnectwithtimeout: symbol not found
Error relocating /us/sbin/unbound-checkconf redisFree: svmbol not found
redisCommand: symbol not found

Do you know what might be missing? Do I need to map a new volume in compose?

Error with custom files

Behaviour

Steps to reproduce this issue

1. Create config folder on docker host
2. docker-compose -d up
3. docker cp unbound:/etc/unbound/unbound.conf . (to config folder)
4. docker restart unbound

Expected behaviour

ubound should start with custom unbound.conf

Actual behaviour

unbound fails to start

Configuration

• Docker version (type docker --version) : 20:10:14
• Docker compose version if applicable (type docker-compose --version) : 1.29.1
• Platform (Debian 9, Ubuntu 18.04, ...) : Ubuntu 20.04
• System info (type uname -a) : Linux localserver 5.13.0-39-generic #44~20.04.1-Ubuntu SMP Thu Mar 24 16:43:35 UTC 2022 x86_64 x86_64 x86_64 GNU/Linux
• Include all necessary configuration files : docker-compose.yml, .env, ...

Docker-compose

  unbound:
    hostname: unbound
    image: crazymax/unbound
    container_name: unbound
    restart: always
    volumes:
      - "${docker}/unbound/config:/config:ro"
    ports:
      - 5053:5053/tcp
      - 5053:5053/udp
    user: 1000:1000

Docker info

Client:
 Context:    default
 Debug Mode: false
 Plugins:
  app: Docker App (Docker Inc., v0.9.1-beta3)
  buildx: Docker Buildx (Docker Inc., v0.8.1-docker)
  scan: Docker Scan (Docker Inc., v0.17.0)

Server:
 Containers: 96
  Running: 94
  Paused: 0
  Stopped: 2
 Images: 100
 Server Version: 20.10.14
 Storage Driver: overlay2
  Backing Filesystem: extfs
  Supports d_type: true
  Native Overlay Diff: true
  userxattr: false
 Logging Driver: json-file
 Cgroup Driver: cgroupfs
 Cgroup Version: 1
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local logentries splunk syslog
 Swarm: inactive
 Runtimes: io.containerd.runc.v2 io.containerd.runtime.v1.linux runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: 3df54a852345ae127d1fa3092b95168e4a88e2f8
 runc version: v1.0.3-0-gf46b6ba
 init version: de40ad0
 Security Options:
  apparmor
  seccomp
   Profile: default
 Kernel Version: 5.13.0-39-generic
 Operating System: Ubuntu 20.04.4 LTS
 OSType: linux
 Architecture: x86_64
 CPUs: 8
 Total Memory: 31.12GiB
 Name: localserver
 ID: TJE6:MOTK:7QFB:G52G:LXBZ:GLLL:4YWV:ZXPR:ASEF:4H5O:Z3DZ:67G2
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 Username: user1
 Registry: https://index.docker.io/v1/
 Labels:
 Experimental: false
 Insecure Registries:
  osu.registry:5000
  127.0.0.0/8
 Live Restore Enabled: false

Logs

/config/unbound.conf:1: error: too many include files
/config/unbound.conf:32: error: too many include files
/config/unbound.conf:32: error: too many include files
read /etc/unbound/unbound.conf failed: 3 errors in configuration file
[1649184966] unbound[1:0] fatal error: Could not read config file: /etc/unbound/unbound.conf. Maybe try unbound -dd, it stays on the commandline to see more errors, or unbound-checkconf

Just thank you for the tls support..

Thank you for making an unbound image with tls support..

docker run --name crazymax-unbound \
    --network=host \
   -v /etc/unbound/crazymax:/config \
    crazymax/unbound

dropped in my old config.. and moved on..

I'll see what it takes to update to 1.17.1 and alpine 3.17.1 as an exercise..

thank you for your time and effort.

(Alma linux apparently has 1.16.x has some crazy startup lag that I cannot overcome.. ) I got knot-resolver going.. but the logging is not the same as unbound..

Anyway, thank you.