Alpine Linux Based Unbound Hyperlocal & DNSSEC Validating DNS Server Multiarch Docker Image

Maintainer

• madnuttah

Statistics

Available Docker Tags

Changes

You can view the changelogs in the Releases section.

Table of Contents

• What is Unbound
• About this Image
• Installation
• How to use this Image
  • Folder Structure
  • Networking
  • Standard Usage
• Documentation and Feedback
  • Documentation
  • Feedback
  • Contributing
• Acknowledgements
• Licenses
• Legal
• Social

What is Unbound

Unbound is a validating, recursive, caching DNS resolver.

It is designed to be fast and lean and incorporates modern features based on open standards. Late 2019, Unbound has been rigorously audited, which means that the code base is more resilient than ever.

Source: unbound.net

About this Image

This container image is based on Alpine Linux with focus on security, performance and a small image size. The unbound process runs in the context of a non-root user, is sealed with chroot and makes use of unprivileged ports (5335 tcp/udp).

Unbound is configured as an DNSSEC validating DNS resolver, which directly queries DNS root servers utilizing zone transfers holding a local copy of the root zone (see IETF RFC 8806) to build a "hyperlocal" setup as an upstream DNS server in combination with Pi-hole for adblocking in mind, but works also as a standalone server. However, even though the image is intended to run a "hyperlocal" setup, it does not necessarily mean that it has to be used that way. You are absolutely free to edit the unbound.conf file according to your own needs and requirements, especially if you'd rather like to use an upstream DNS server which provides DoT or DoH features instead of using the "hyperlocal" feature.

To provide always the latest versions, the following software components are self compiled in the build process using separated workflows and are not just installed:

• Unbound
• Libevent
• OpenSSL

The image is completely built online via a GitHub Action and not locally on my systems. All components as well as the Internic files (root.hints and root.zone) are verified with their corresponding PGP keys and signature files if available to guarantee maximum security and trust.

Unbound is compiled with hardening security features such as PIE (Position Independent Executables), which randomizes the application's position in memory which makes attacks more difficult and RELRO (Relocation Read-Only) which also can mitigate exploitations.

I hope you enjoy the image.

Installation

Current multiarch-builds of the image are available on Docker Hub and is the recommended source of installation on any Linux-based 386, arm, arm64 or amd64 platform.

How to use this Image

You should adapt the /usr/local/unbound/unbound.conf file and my example docker-compose.yaml file to your needs. The compose file also deploys Pi-hole for blocking ads and to prevent tracking as well as Watchtower for keeping your images up to date.

To provide a better structuring of the unbound.conf file, directories for optionally storing zone and other configuration files as well as for your certificates and the unbound.log file have been created and can be mounted as volumes:

• /usr/local/unbound/certs.d/ for storing your certificate files.

• /usr/local/unbound/conf.d/ for your configuration files like interfaces.conf, performance.conf, security.conf, etc.

• /usr/local/unbound/iana.d/ for the root.key, root.hints and root.zone files in case you need to update or view them for troubleshooting and debugging purposes.

• /usr/local/unbound/log.d/unbound.log in case you need to access it for troubleshooting and debugging purposes.

• /usr/local/unbound/zones.d/ for your zone configuration files like auth-zone.conf, stub-zone.conf, forward-zone.conf, etc.

The config files in the conf.d and zones.d folders must be named with the suffix .conf to prevent issues with specific host configurations.

The splitted configuration files located in unbound/examples/usr/local/unbound are only meant to give you an impression on how to separating and structuring the configs. Please mind that those files are examples which also needs to be edited and even updated (root.key, root.zone, root.hints in the iana.d folder) to make them work for your environment if you intend to use them. It might be necessary to fix permissions and ownership of the files put in the persistent volumes if unbound refuses to start. You can access the running image by executing the following command in your shell: sudo docker exec -ti madnuttah-unbound /bin/sh. If you have assigned a different name for the image than madnuttah-unbound, this must be adjusted of course.

Other than that, splitting ain't really necessary as your standard unbound.conf will perfectly do the job.

Folder Structure

/usr/local/
├── libevent/
│   └── ...
├── openssl/
│   └── ... 
├── sbin/
│   ├── unbound.sh 
│   └── ...
├── unbound/
│   ├── certs.d/
│   │   └── ...
│   ├── conf.d/
│   │   └── *.conf
│   ├── iana.d/
│   │   ├── root.hints
│   │   ├── root.key
│   │   └── root.zone
│   ├── log.d/
│   │   └── unbound.log
│   ├── unbound.d/
│   │   ├── lib/
│   │   │   └── libunbound.*
│   │   ├── sbin/
│   │   │   ├── unbound
│   │   │   ├── unbound-anchor
│   │   │   ├── unbound-checkconf
│   │   │   ├── unbound-control
│   │   │   ├── unbound-control-setup
│   │   │   └── unbound-host
│   │   ├── null
│   │   ├── random
│   │   ├── urandom
│   │   └── unbound.pid
│   ├── zones.d/
│   │   └── *.conf
│   └── unbound.conf 
├── ...
...

Networking

If you want to use this image as a standalone DNS resolver without Pi-hole, the given ports must be changed to 53 (TCP/UDP) in your unbound.conf and docker-compose.yaml.

Standard Usage

The best way to get started is using docker-compose. I have provided a combined Pi-hole/Unbound/Watchtower docker-compose.yaml sample which I'm using in slightly modified form that makes use of a MACVLAN network which must be adapted to your network environment and to suit your needs for development or production use. Especially all entries in angle brackets (<>) needs your very attention!

I prefer using a MACVLAN network configuration instead of a bridged or rather unsafe host network, but other network configurations will run as well.

Anyway, you can also spin up the container with the following command:

docker run --name madnuttah-unbound -d \
-p 5335:5335/udp \
-p 5335:5335/tcp \
--restart=unless-stopped \
madnuttah/unbound:latest

Documentation and Feedback

Documentation

In-depth documentation for NLnetLabs Unbound is available on the Unbound project's website and here goes a direct link to the documentation of the default unbound.conf file.

There's also a dedicated Unbound documentation website which can be accessed using this link.

Feedback

Feel free to contact me through a GitHub Issue if you have any questions, requests for new features or encounter problems with the image.

Contributing

If you like to contribute to this repository, take a look at the Contributing Guidelines.

Acknowledgements

• Alpine Linux
• Docker
• Unbound
• OpenSSL
• Libevent
• Pi-hole
• Watchtower
• Thank you for using my image ❤️

Licenses

License

Unless otherwise specified, all code is released under the MIT license. See the LICENSE for details.

Licenses for other components

• Docker: Apache 2.0
• Unbound: BSD License
• OpenSSL: Apache-style license
• Libevent: BSD License

Legal

Please note that this is a work of a private contributor and I'm neither affiliated with NLnetLabs or Pi-hole nor is NLnetLabs or Pi-hole involved in the development of the image. The marks and properties, 'Unbound' and 'Pi-hole' are properties of NLnetLabs and Pi-hole respectively. All rights in the source codes, including logos relating to said marks and properties belong to their respective owners.

Social

Stay up-to-date with the development by following my social media accounts: