docker-bind

A Docker image of the ISC Bind/Bind9/Named DNS service that has been set up so it is easy to configure when running inside a container.

The program is built directly from source, in order to get the latest version, and there are both Debian and Alpine images available. Useful configuration files and folders (similar to what is found in the Debian packages) are included to make it simpler to set up a DNS server.

There is also an Ansible role using this image, if that is of interest.

ℹ️ This is still a bit of work in progress, so if something isn't working for you I am very interested in being notified about it.

Acknowledgments and Thanks

This repository was originally a fork of ventz/docker-bind, but what was supposed to be just a small pull request turned into a complete rewrite. While very little of the original code remains it would be dishonest to not keep the commit history since without it I would not have found inspiration to make my own version.

There is also an official Docker image (source) but I found it have some configuration options I didn't like and chose to try to build my own instead.

Usage

The amount of options available for Bind is absolutely enormous, and what options to use will be very different depending on how you intend to run your instance so I will not even try to list suggestions here. But to just get you started we will set up a super simple forwarding server, so it becomes easier to understand what configuration files are needed and where they are expected to be found.

Full Bind documentation found here: https://bind9.readthedocs.io/en/stable/

Available Environment Variables

ℹ️ It is possible to change these environment variables, but you will most likely break things.

• BIND_LOG: Input argument for configuring stderr or file logging (default: -f)
• BIND_USER: The username the service will run as (default: alpine=named, debian=bind)

Configuration Files and Folders

There are five folders in this image that are good to know about:

1. /etc/bind/local-config/ - Your custom configs -> Mount your configs here.
2. /var/cache/bind - Default "workdir" for Bind -> Probably good to host mount.
3. /var/log/bind - Recommended folder to output logs to -> Host mount if you want.
4. /var/lib/bind - Suggested folder to place zone files in -> Host mount if used.
5. /entrypoint.d/ - Place any scripts that should be executed at startup here.

1. Your Custom Configs

When the container starts it will launch Bind which will read the main config file /etc/bind/named.conf, however, that one has only the following content:

include "/etc/bind/local-config/named.conf.logging";
include "/etc/bind/local-config/named.conf.options";
include "/etc/bind/local-config/named.conf.local";

What this means is that these three files are expected to be present when the container starts, and some basic (but fully functioning) examples are available inside the example-configs/ folder (see how they are mounted in the Run section).

⚠️ Logging in Bind is a little bit weird, so if anything in the config is wrong it will not output any logs unless you set BIND_LOG=-g. Use this for debugging and then switch back to default.

By having all the user defined files inside this local-config/ sub-folder it is possible for this image to include up to date versions of the "default" config files in the parent folder without the users having to update their paths.

Please also look at the rndc section for a simple way to create the rndc key needed for communicating with Bind.

2. The Cache

The other important location is the "working directory" (or cache) of the server that is defined at the top of the named.conf.options file. This is the location where slave zone files will be written, or other stuff that needs to be cached, so for persistence I recommend to host mount this folder and make sure Bind is allowed to write to it (root:101 and 0775).

This is also the directory from which any relative file paths, defined in your configs, will be based on. The Debian package uses /var/cache/bind for this, so that is what we default to in this image as well, but there is nothing stopping you from changing this to whatever you want.

3. The Logs

If you choose to output logs to a file, like in the logging example, the /var/log/bind directory is a good location to use inside the container. Host mount it in order to be able to read the logs outside the container.

If you are fine with just letting Docker capture and manage the logs you can remove the "file" configuration section, and just let it output to stdout/stderr.

4. Your Zone Files

The Debian installation package claims that /var/lib/bind is usually the place where your managed zone files are placed, but personally I just place everything inside the cache directory in order to use relative paths everywhere.

This approach aligns with ISC examples which usually defines the directory option and use a folder structure like this (basically /var/cache/bind changed to /var/named) to separate the different use cases:

/var/named/
├── master/       manually maintained primary zone files
├── slave/        downloaded secondary-zone copies
├── dynamic/      dynamically updated zones and .jnl files
├── data/         managed keys, NZD state, dumps, etc.
├── keys/         DNSSEC private keys
└── run/          PID/control sockets, when needed

However, it is up to you how you like to organize it, since you have full control on whether you use absolute or relative paths for your "zone" declarations. You can keep directory /var/cache/bind, so all volatile data is written there, and then provide absolute paths to your master zones somewhere inside /var/lib/bind/.

5. The entrypoint Scripts

The final location that might be of interest is the /entrypoint.d/ folder, since the main entrypoint.sh will look inside it for any files ending with .sh and try to execute them in alphabetical order. This allows you to run custom commands before the Bind service is started.

Input Arguments

Any extra input arguments provided as the CMD, when starting the image, will be appended directly to the Bind service. Please take a look at the last line in entrypoint.sh to see how it works.

Create rndc.key

At the top of the named.conf.local file we include an "rndc key" which needs to be created manually by you as it should be unique and secret. You can have the file written to the example-configs/ folder by running the following command:

docker run -it --rm \
    -v $(pwd)/example-configs:/etc/bind/local-config \
    --entrypoint=/bin/sh \
    jonasal/bind:9 \
    -c 'rndc-confgen -a -A hmac-sha256 -b 256 -u "${BIND_USER}" -c /etc/bind/local-config/rndc.key'

Run

After you have read through all the steps above we can finally start the image:

docker run -it --rm \
    -p 54:53 -p 54:53/udp -p 953:953 \
    -v $(pwd)/example-configs:/etc/bind/local-config \
    -v $(pwd)/zones:/var/cache/bind \
    jonasal/bind:9 \
    -4

Important to note here is that we forward port 54 on the host to the "correct" port 53 inside the container. I do this because some Linux distributions comes with the systemd-resolved service running which already use port 53. This is a problem if you want to run this image as a real DNS server, so you will have to disable it if it causes you trouble.

Furthermore, at the very end of the command we include -4, and this tells Bind to not enable any IPv6 functionality. The reason for this is that by default no IPv6 traffic is handled by Docker and unnecessary error messages will be printed unless the flag is provided. Read more about this in the Docker Network Mode section.

Verify

In order to verify that Bind works, after running the command above, is to just make a quick query to your machine on port 54 and see if anything is printed in the container logs.

dig @127.0.0.1 -p 54 google.se

Docker Network Mode

As was previously mentioned Docker does not have IPv6 enabled by default, so it is recommended to start Bind with the -4 flag to tell it to run in just IPv4 mode. But if you do want to run it for both IP versions I would suggest you first read this to get a better understanding of the quirks that currently exist, and I would actually suggest you just run this container on the host network to make your life easier.

Also, don't forget to change the listen-on-v6 directive in the options config file.

docker run -it --rm \
    --network host \
    -v $(pwd)/example-configs:/etc/bind/local-config \
    -v $(pwd)/zones:/var/cache/bind \
    jonasal/bind:9

You could probably do some fiddling with macvlan to achieve the same stuff, but I would not bother.

Further reading

As was mentioned in the beginning there exists a plethora of ways on how to configure Bind, so you will need to do some of your own research in order to function just as you want. However, here is a collection of links from where you can start your journey:

• https://bind9.readthedocs.io/en/stable/
• https://wiki.debian.org/Bind9
• https://help.ubuntu.com/community/BIND9ServerHowto
• https://www.zytrax.com/books/dns/ch7/
• https://www.digitalocean.com/community/tutorials/how-to-configure-bind-as-a-private-network-dns-server-on-ubuntu-18-04
• https://kb.isc.org/docs/aa-01526
• https://www.zytrax.com/books/dns/ch7/logging.html