Build status (click to expand)
This repository provides a lightweight Alpine Linux based Docker image running Unbound, an open source high performance DNS resolver developed by the people at NLnet Labs. The image is a secure single layer distroless scratch build that follows best practice principles and is suitable for professional and personal use alike.
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 | 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.
Docker containers are most easily used with Docker Compose.
Important
Please read the Documentation to learn how to get this image running.
Example Docker Compose files can be found here.
If you prefer Podman and systemd, example Quadlets can be found here.
This image is published in four variants: standard, QUIC, canary, and canary QUIC.
All tags follow a consistent versioning scheme based on the upstream Unbound release.
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:
<UNBOUND_VERSION>-<REVISION>
e.g. 1.1.0-0
QUIC enabled images follow the same versioning scheme as the standard images but append -quic:
docker pull madnuttah/unbound:latest-quic
docker pull madnuttah/unbound:1.1.0-0-quic
Versioning scheme:
<UNBOUND_VERSION>-<REVISION>-quic
e.g. 1.1.0-0-quic
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.
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.
Note
Canary builds may contain bugs and are not recommended for production use. They are untested and unsupported.
You can view the changes in the Releases section.
If you have questions or encounter issues, please open a GitHub Issue.
Feature requests and general discussion are welcome in the repository Discussions tab.
You can also reach us on Fosstodon:
- Alpine Linux
- Docker
- Unbound
- OpenSSL
- Redis
- Pi-hole
- Aqua Security
- zizmor
- The many Docker images that inspired this project
Unless otherwise specified, all code is released under the MIT license.
See the LICENSE for details.
- Docker: Apache 2.0
- Unbound: BSD License
- OpenSSL: Apache style license
Please note that this is a work of private contributors and we're neither affiliated with NLnet Labs, Pi-hole or AdGuard nor is NLnet Labs, Pi-hole or AdGuard involved in the development of the image. The marks and properties 'Unbound', 'Pi-hole' and 'AdGuard Home' are properties of NLnet Labs, Pi-hole and AdGuard respectively. All rights in the source codes, including logos relating to said marks and properties belong to their respective owners.
In case you would like to donate money, please rather spend it on the upstream projects this image depends on.
If you like what we do and if you find this image protecting your privacy and giving back your DNS liberty useful - spread the word, fork our repo, open an issue, make a pull request and don't forget to leave a star on Docker Hub and GitHub. Many thanks for your support!