madnuttah/unbound-docker
GitHub: madnuttah/unbound-docker
Stars: 354 | Forks: 31
# Alpine Linux Based DNSSEC Validating Recursive Unbound DNS Resolver Docker Image
[](https://github.com/madnuttah/unbound-docker/blob/main/.github/workflows/cd-check-unbound-release.yaml) [](https://github.com/madnuttah/unbound-docker/blob/main/.github/workflows/cd-build-unbound.yaml) [](https://github.com/madnuttah/unbound-docker/blob/main/.github/workflows/cd-build-canary-unbound.yaml)
[](https://github.com/madnuttah/unbound-docker/releases)
[](https://github.com/madnuttah/openssl-buildenv/releases)
[](https://github.com/madnuttah/unbound-docker/actions/workflows/cd-gh-action-zizmor-scan.yaml)
[](https://github.com/madnuttah/unbound-docker/blob/main/.github/workflows/cd-security-scan.yaml)
This repository provides a lightweight Alpine Linux based Docker image running [Unbound](https://unbound.net), an open source high performance DNS resolver developed by the people at [NLnet Labs](https://nlnetlabs.nl). The image is a secure single layer distroless scratch build that follows best practice principles and is suitable for professional and personal use alike.
| Feature | Supported | Explanation | | ---------------------------------------- | --------- | ----------- | | Unprivileged user | yes | Runs Unbound without root to reduce attack surface. | | Unprivileged port (privileged possible) | yes | Allows binding to high ports by default or low ports when needed. | | Custom UID and GID build and environment variables | yes | Lets you match container permissions to host requirements. | | Optional full rootless mode | yes | Enables running the container without any root privileges. | | CD built single layer distroless scratch image running Alpine Linux | yes | Produces a minimal and secure runtime with no package manager or shell. | | Per hardware architecture optimized and CD built [OpenSSL&OpenSSL+QUIC](https://github.com/madnuttah/openssl-buildenv) | yes | Ensures optimal crypto performance and QUIC support per architecture. | | Libevent | yes | Provides efficient event handling for high performance DNS resolution. | | Recursive DNS as default | yes | Configured to perform full recursion without relying on upstream resolvers. | | DNSSEC | yes | Validates DNS responses cryptographically for authenticity. | | DNSCrypt | yes | Supports encrypted DNS queries using the DNSCrypt protocol. | | DNSTap | yes | Allows structured logging of DNS queries for analysis and debugging. | | DNS64 | yes | Synthesizes IPv6 addresses for IPv4 only destinations. | | DNS over HTTPS | yes | Accepts and serves DNS queries over HTTPS. | | DNS over TLS | yes | Accepts and serves DNS queries over TLS. | | DNS over Quic (separate [-quic] builds) | yes | Provides DNS over QUIC support in dedicated QUIC enabled images. | | Redis via UNIX socket or network | yes | Enables caching or persistent storage through Redis. | | EDNS Client Subnet | yes | Supports forwarding client subnet information when required. | | Optional privacy respecting and meaningful healthcheck | yes | Offers a healthcheck that avoids leaking DNS queries. | | Optional Unbound statistics for Grafana via Zabbix without third party tools | yes | Exposes metrics directly for monitoring without extra exporters. | | Python | no | Python is intentionally excluded to keep the image minimal. |
This image is built for a wide range of hardware architectures. All builds are produced using Docker Buildx with QEMU emulation where required and optimized OpenSSL or OpenSSL QUIC build environments. | Architecture | Supported | Notes | |-------------|-----------|-------| | linux/amd64 | yes | Fully supported and optimized | | linux/arm64 | yes | Fully supported and optimized | | linux/386 | yes | Legacy compatibility | | linux/arm/v6 | yes | For older ARM devices | | linux/arm/v7 | yes | Common for SBCs like Raspberry Pi 2 and 3 | | linux/ppc64le | yes | Little endian PowerPC | | linux/s390x | yes | IBM Z and LinuxONE | | linux/riscv64 | yes | Experimental but supported | All architectures are built and published automatically through continuous delivery pipelines.
## Getting started
Docker containers are most easily used with Docker Compose.
## Available Docker Tags
This image is published in four variants: standard, QUIC, canary, and canary QUIC.
### Standard Images (DNS over TLS/DoT, UDP, TCP)
The standard Unbound images can be pulled using the latest tag or a specific version:
docker pull madnuttah/unbound:latest
docker pull madnuttah/unbound:1.1.0-0
Versioning scheme:
-
e.g. 1.1.0-0
### QUIC Images (DNS over QUIC/DoQ)
docker pull madnuttah/unbound:latest-quic
docker pull madnuttah/unbound:1.1.0-0-quic
Versioning scheme:
--quic
e.g. 1.1.0-0-quic
### Canary Images (Nightly Builds)
Nightly builds of the standard image are published under the canary tag:
docker pull madnuttah/unbound:canary
These builds track the latest upstream Unbound master branch.
### Canary QUIC Images (Nightly QUIC Builds)
Nightly QUIC enabled builds are available under the canary-quic tag:
docker pull madnuttah/unbound:canary-quic
These builds combine the latest Unbound master branch with the QUIC enabled OpenSSL and NGTCP2 stack.
## Changes
You can view the changes in the [Releases](https://github.com/madnuttah/unbound-docker/releases) section.
## Feedback
If you have questions or encounter issues, please open a [GitHub Issue](https://github.com/madnuttah/unbound-docker/issues).
Feature requests and general discussion are welcome in the repository [Discussions](https://github.com/madnuttah/unbound-docker/discussions) tab.
You can also reach us on Fosstodon:
## Acknowledgements
- [Alpine Linux](https://www.alpinelinux.org/)
- [Docker](https://www.docker.com/)
- [Unbound](https://unbound.net/)
- [OpenSSL](https://www.openssl.org/)
- [Redis](https://redis.io/)
- [Pi-hole](https://pi-hole.net/)
- [Aqua Security](https://trivy.dev/)
- [zizmor](https://github.com/zizmorcore/zizmor)
- The many Docker images that inspired this project
## Licenses
### License
Unless otherwise specified, all code is released under the MIT license.
See the [LICENSE](https://github.com/madnuttah/unbound-docker/blob/main/LICENSE) for details.
### Licenses for other components
- Docker: [Apache 2.0](https://github.com/docker/docker/blob/master/LICENSE)
- Unbound: [BSD License](https://unbound.nlnetlabs.nl/svn/trunk/LICENSE)
- OpenSSL: [Apache style license](https://www.openssl.org/source/license.html)
## Legal
## Supporting our mission
Build status (click to expand)
[](https://github.com/madnuttah/unbound-docker/blob/main/.github/workflows/cd-check-unbound-release.yaml) [](https://github.com/madnuttah/unbound-docker/blob/main/.github/workflows/cd-build-unbound.yaml) [](https://github.com/madnuttah/unbound-docker/blob/main/.github/workflows/cd-build-canary-unbound.yaml)
Features (click to expand)
| Feature | Supported | Explanation | | ---------------------------------------- | --------- | ----------- | | Unprivileged user | yes | Runs Unbound without root to reduce attack surface. | | Unprivileged port (privileged possible) | yes | Allows binding to high ports by default or low ports when needed. | | Custom UID and GID build and environment variables | yes | Lets you match container permissions to host requirements. | | Optional full rootless mode | yes | Enables running the container without any root privileges. | | CD built single layer distroless scratch image running Alpine Linux | yes | Produces a minimal and secure runtime with no package manager or shell. | | Per hardware architecture optimized and CD built [OpenSSL&OpenSSL+QUIC](https://github.com/madnuttah/openssl-buildenv) | yes | Ensures optimal crypto performance and QUIC support per architecture. | | Libevent | yes | Provides efficient event handling for high performance DNS resolution. | | Recursive DNS as default | yes | Configured to perform full recursion without relying on upstream resolvers. | | DNSSEC | yes | Validates DNS responses cryptographically for authenticity. | | DNSCrypt | yes | Supports encrypted DNS queries using the DNSCrypt protocol. | | DNSTap | yes | Allows structured logging of DNS queries for analysis and debugging. | | DNS64 | yes | Synthesizes IPv6 addresses for IPv4 only destinations. | | DNS over HTTPS | yes | Accepts and serves DNS queries over HTTPS. | | DNS over TLS | yes | Accepts and serves DNS queries over TLS. | | DNS over Quic (separate [-quic] builds) | yes | Provides DNS over QUIC support in dedicated QUIC enabled images. | | Redis via UNIX socket or network | yes | Enables caching or persistent storage through Redis. | | EDNS Client Subnet | yes | Supports forwarding client subnet information when required. | | Optional privacy respecting and meaningful healthcheck | yes | Offers a healthcheck that avoids leaking DNS queries. | | Optional Unbound statistics for Grafana via Zabbix without third party tools | yes | Exposes metrics directly for monitoring without extra exporters. | | Python | no | Python is intentionally excluded to keep the image minimal. |
Supported Architectures (click to expand)
This image is built for a wide range of hardware architectures. All builds are produced using Docker Buildx with QEMU emulation where required and optimized OpenSSL or OpenSSL QUIC build environments. | Architecture | Supported | Notes | |-------------|-----------|-------| | linux/amd64 | yes | Fully supported and optimized | | linux/arm64 | yes | Fully supported and optimized | | linux/386 | yes | Legacy compatibility | | linux/arm/v6 | yes | For older ARM devices | | linux/arm/v7 | yes | Common for SBCs like Raspberry Pi 2 and 3 | | linux/ppc64le | yes | Little endian PowerPC | | linux/s390x | yes | IBM Z and LinuxONE | | linux/riscv64 | yes | Experimental but supported | All architectures are built and published automatically through continuous delivery pipelines.