Bind Docker

---

The original Bind Docker was created and maintained by cytopia in the cytopia/docker-bind repository.

Thanks to cytopia and the devilbox project.

---

Available Architectures: amd64, arm/v7

Bind caching DNS server based on Alpine and Debian slim with support for DNS forwarders, infinite wild-card DNS, infinite extra hosts, reverse DNS, DNSSEC timing settings and others.

Bind Project	Reference Implementation
Bind DNS Server	The Devilbox

🐋 Available Docker tags

latest stable alpine

docker pull johnea/bind

Rolling Releases

The following Docker image tags are rolling releases and are built and updated every night.

Docker Tag	Git Ref	Available Architectures
latest	master	amd64, arm64
stable	master	amd64, arm64
alpine	master	amd64, arm64

Point in time releases

The following Docker image tags are built once and can be used for reproducible builds. Its version never changes so you will have to update tags in your pipelines from time to time in order to stay up-to-date.

Docker Tag	Git Ref	Available Architectures
<tag>	git: <tag>	amd64, arm64
<tag>-stable	git: <tag>	amd64, arm64
<tag>-alpine	git: <tag>	amd64, arm64

🛈 Where <tag> refers to the chosen git tag from this repository.
⚠ Warning: The latest available git tag is also build every night and considered a rolling tag.

---

Table of Contents

1. Environment variables
   1. Required environment variables
   2. Optional environment variables
      1. DEBUG_ENTRYPOINT
      2. DOCKER_LOGS
      3. DNS_A
      4. DNS_CNAME
      5. DNS_PTR
      6. DNSSEC_VALIDATE
      7. DNS_FORWARDER
      8. MAX_CACHE_SIZE
      9. TTL_TIME
      10. REFRESH_TIME
      11. RETRY_TIME
      12. EXPIRY_TIME
      13. MAX_CACHE_TIME
      14. ALLOW_QUERY
      15. ALLOW_RECURSION
2. Volumes
3. Exposed Ports
4. Examples
   1. Default run
   2. Wildcard domain
   3. Wildcard subdomain
   4. Wildcard TLD
   5. Wildcard TLD and reverse DNS entry
   6. Wildcard TLD and DNS resolver
   7. Wildcard TLD, DNS resolver and extra hosts
   8. Extra hosts, DNS resolver, allow query, and allow recursion
5. Host integration
6. Sister Projects
7. Community
8. Articles
9. Credits
10. Maintainer
11. License

---

∑ Environment Variables

Required environment variables

• None

Optional environment variables

Variable	Type	Default	Description
DEBUG	bool	0	Set to 1 in order to add set -x to entrypoint script for bash debugging
DEBUG_ENTRYPOINT	bool	0	Show shell commands executed during start. Values: 0, 1 or 2
DOCKER_LOGS	bool	0	Set to 1 to log info and queries to Docker logs.
DNS_A	string		Comma separated list of A records (wildcard supported).
DNS_CNAME	string		Comma separated list of CNAME records (wildcard supported).
DNS_PTR	string		Comma separated list of PTR records (reverse DNS).
DNSSEC_VALIDATE	string	no	Control the behaviour of DNSSEC validation. The default is to not validate: no. Other possible values are: yes and auto.
DNS_FORWARDER	string		Specify a comma separated list of IP addresses as custom DNS resolver. This is useful if your LAN already has a DNS server which adds custom/internal domains and you still want to keep them in this DNS server Example: DNS_FORWARDER=8.8.8.8,8.8.4.4
MAX_CACHE_SIZE	size	90%	Amount of memory used by the server (cached results)
TTL_TIME	int	3600	(time in seconds) see bind ttl and bind soa
REFRESH_TIME	int	1200	(Time in seconds) See BIND SOA
RETRY_TIME	int	180	(Time in seconds) See BIND SOA
EXPIRY_TIME	int	1209600	(Time in seconds) See BIND SOA
MAX_CACHE_TIME	int	10800	(Time in seconds) See BIND SOA
ALLOW_QUERY	string		Specify a comma separated list of IP addresses with optional CIDR mask to allow queries from a specific IP address or ranges of IP addresses. This allows for control over who is allowed to query the DNS server. If not specified all hosts are allowed to make queries (defaults to any). See BIND QUERIES Example: ALLOW_QUERY=192.168.1.0/24,127.0.0.1
ALLOW_RECURSION	string		Specify a comma separated list of IP addresses with optional CIDR mask to allow queries from a specific IP address or ranges of IP addresses. This option allows this DNS server to forward a request to another DNS server when an address cannot be resolved. If not present the allow-query-cache default is assumed. See BIND QUERIES Example: ALLOW_RECURSION=192.168.1.0/24,127.0.0.1

DEBUG_ENTRYPOINT

• If set to 0, only warnings and errors are shown
• If set to 1, info, warnings and errors are shown
• If set to 2, info, warnings and errors are shown, as well as commands executed during startup

DOCKER_LOGS

• If set to 0, no additional logging is done during run-time
• If set to 1, BIND is more verbose during run-time and shows asked queries as well as general information

DNS_A

The DNS_A option allows you to specify one or more A records (including wildcard if required) which can either be a full TLD, a domain or any kind of subdomain. It allows you to map your Domain to a specific IP address.

The general format is as follows:

# Structure
DNS_A='tld1=1.1.1.1, tld2=2.2.2.2, *.tld3=3.3.3.3'

Some examples:

# 1. One entry:
# The following catches all queries to *.tld (wildcard) and redirects them to 192.168.0.1
DNS_A='*.tld=192.168.0.1'

# 2. Two entries:
# The following catches all queries to *.tld and redirects them to 192.168.0.1
# As well as all queries from *.example.org and redirects them to 192.168.0.2
DNS_A='*.tld=192.168.0.1, *.example.org=192.168.0.2'

DNS_CNAME

The DNS_CNAME option allows you to specify one or more CNAME records (including wildcard if required) which can either be a full TLD, a domain or any kind of subdomain. It allows you to map your Domain to a specific IP address.

The general format is as follows:

# Structure
DNS_CNAME='tld1=google.com, tld2=www.google.com, *.tld3=example.org'

Some examples:

# 1. Using CNAME's for resolving:
# The following catches all queries to *.tld and redirects them to whatever
# IP example.org resolved to
DNS_CNAME='*.tld=example.org'

DNS_PTR

The DNS_PTR option allows you to specify PTR records (reverse DNS).

The general format is as follows:

# Structure
DNS_PTR='192.168.0.1=www.google.com, 192.168.0.2=ftp.google.com'

Some examples:

# 1. Adding reverse DNS:
# The following adds reverse DNS from 192.168.0.1 to resolve to tld
DNS_PTR='192.168.0.1=tld'

DNSSEC_VALIDATE

The DNSSEC_VALIDATE variable defines the DNSSEC validation. Default is to not validate (no). Possible values are:

• yes - DNSSEC validation is enabled, but a trust anchor must be manually configured. No validation will actually take place.
• no - DNSSEC validation is disabled, and recursive server will behave in the "old fashioned" way of performing insecure DNS lookups, until you have manually configured at least one trusted key.
• auto - DNSSEC validation is enabled, and a default trust anchor (included as part of BIND) for the DNS root zone is used.

DNS_FORWARDER

By default this dockerized BIND is not acting as a DNS forwarder, so it will not have any external DNS available. In order to apply external DNS forwarding, you will have to specify one or more external DNS server. This could be the one's from google for example (8.8.8.8 and 8.8.4.4) or any others you prefer. In case your LAN has its own DNS server with already defined custom DNS records that you need to make available, you should use them.

# Structure (comma separated list of IP addresses)
DNS_FORWARDER='8.8.8.8,8.8.4.4'

Some examples

DNS_FORWARDER='8.8.8.8'
DNS_FORWARDER='8.8.8.8,192.168.0.10'

MAX_CACHE_SIZE

The amount of RAM used by the server to store results. You can use relative (percent) or absolute (bytes) values. Examples:

• MAX_CACHE_SIZE=30% (Use 30% of the systems memory)
• MAX_CACHE_SIZE=512M (Use 512 Megabytes)
• MAX_CACHE_SIZE=2G (Use 2 Gigabytes)

TTL_TIME

Specify time in seconds. For more information regarding this setting, see BIND TTL and BIND SOA

REFRESH_TIME

Specify time in seconds. For more information regarding this setting, see BIND SOA

RETRY_TIME

Specify time in seconds. For more information regarding this setting, see BIND SOA

EXPIRY_TIME

Specify time in seconds. For more information regarding this setting, see BIND SOA

MAX_CACHE_TIME

Specify time in seconds. For more information regarding this setting, see BIND SOA

ALLOW_QUERY

By default this dockerized BIND does not specify query rules. This exposes the allow-query options to specify who is allowed to query for results. Note that ACLs are not yet handled.

# Structure (comma separated list of IP addresses, IP addresses with CIDR mask, or address match list names "none", "any", "localhost", and "localnets")
ALLOW_QUERY='192.168.1.0/24,127.0.0.1'

Some examples

ALLOW_QUERY='any'
ALLOW_QUERY='192.168.1.0/24,127.0.0.1'

ALLOW_RECURSION

By default this dockerized BIND does not allow DNS recursion. If BIND cannot resolve an address it will act as a DNS client and forward the request to another DNS server. This server is specified in the DNS_FORWARDER list. Note that ACLs are not yet handled.

# Structure (comma separated list of IP addresses, IP addresses with CIDR mask, or address match list names "none", "any", "localhost", and "localnets")
ALLOW_RECURSION='192.168.1.0/24,127.0.0.1'

Some examples

ALLOW_RECURSION='any'
ALLOW_RECURSION='192.168.1.0/24,127.0.0.1'

📂 Volumes

• None

🖧 Exposed Ports

Docker	Description
53	DNS Resolver
53/udp	DNS Resolver

💡 Examples

The following examples start the container in foreground and use -i, so you can easily stop it by pressing <Ctrl> + c. For a production run, you would rather use -d to send it to the background.

Default run

Exposing the port is mandatory if you want to use it for your host operating system.

docker run -i \
    -p 53:53/tcp \
    -p 53:53/udp \
    -t johnea/bind

Wildcard domain

Let's add a wildcard zone for *.example.com. All subdomains (but not example.com itself) will resolve to 192.168.0.1.

docker run -i \
    -p 53:53/tcp \
    -p 53:53/udp \
    -e DNS_A='*.example.com=192.168.0.1' \
    -t johnea/bind

Wildcard subdomain

Let's add a wildcard zone for *.aws.example.com. All subdomains (but not aws.example.com itself) will resolve to 192.168.0.1.

docker run -i \
    -p 53:53/tcp \
    -p 53:53/udp \
    -e DNS_A='*.aws.example.com=192.168.0.1' \
    -t johnea/bind

Wildcard TLD

Let's add a wildcard zone for *.loc. All domains, subdomain (but not loc itself) will resolve to 192.168.0.4.

docker run -i \
    -p 53:53/tcp \
    -p 53:53/udp \
    -e DNS_A='*.loc=192.168.0.4' \
    -t johnea/bind

Wildcard TLD and reverse DNS entry

Let's add a wildcard zone for *.loc, and an A record for loc. All domains, subdomain and loc itself will resolve to 192.168.0.4. Additionally we specify that host.loc will be the reverse loopup for 192.168.0.4.

docker run -i \
    -p 53:53/tcp \
    -p 53:53/udp \
    -e DNS_A='*.loc=192.168.0.4, loc=192.168.0.4' \
    -e DNS_PTR='192.168.0.4=host.loc' \
    -t johnea/bind

Wildcard TLD and DNS resolver

Let's add a wildcard zone for *.loc. All its domains (but not the domain itself) will resolve to 192.168.0.4.

Let's also hook in our imaginary corporate DNS server into this container, so we can make use of any already defined custom DNS entries by that nameserver.

• loc and all its subdomains (such as: hostname.loc) will point to 192.168.0.1:
• Your corporate DNS servers are 10.0.15.1 and 10.0.15.2

docker run -i \
    -p 53:53/tcp \
    -p 53:53/udp \
    -e DNS_A='*.loc=192.168.0.1' \
    -e DNS_FORWARDER=10.0.15.1,10.0.15.2 \
    -t johnea/bind

Wildcard TLD, DNS resolver and extra hosts

• All subdomains of loc (but not loc itself) will point to 192.168.0.1
• Your corporate DNS servers are 10.0.15.1 and 10.0.15.2
• Also add two additional hosts with A and PTR records:
  • host5.loc -> 192.168.0.2
  • host5.org -> 192.168.0.3

docker run -i \
    -p 53:53/tcp \
    -p 53:53/udp \
    -e DNS_A='*.loc=192.168.0.1, host5.loc=192.168.0.2, host5.org=192.168.0.3' \
    -e DNS_PTR='192.168.0.2=host5.loc, 192.168.0.3=host5.org' \
    -e DNS_FORWARDER=10.0.15.1,10.0.15.2 \
    -t johnea/bind

Extra hosts, DNS resolver, allow query, and allow recursion

• Your trusted external DNS servers are 8.8.8.8 and 8.8.4.4 (google DNS servers)
• Allow queries from:
  • All 192.168.0.xxx addresses
  • Localhost aka 127.0.0.1
• Allow recursion to resolve other queries (such as www.google.com) from:
  • All 192.168.0.xxx addresses
  • Localhost aka 127.0.0.1
• Add an extra hosts with custom DNS:
  • host1 -> 192.168.0.11

docker run -i \
    -p 53:53/tcp \
    -p 53:53/udp \
    -e DNS_A='host1=192.168.0.11' \
    -e DNS_FORWARDER=8.8.8.8,8.8.4.4 \
    -e ALLOW_QUERY=192.168.0.0/24,127.0.0.1 \
    -e ALLOW_RECURSION=192.168.0.0/24,127.0.0.1 \
    -t johnea/bind

🔧 Host integration

You can run this DNS container locally without having to worry to affect any corporate DNS server that are given to you via DHCP.

Add the following line to the very beginning to /etc/dhcp/dhclient.conf:

prepend domain-name-servers 127.0.0.1;

Restart network manager

# Via service command
sudo service network-manager restart

# Or the systemd way
sudo systemctl restart network-manager

This will make sure that whenever your /etc/resolv.conf is deployed, you will have 127.0.0.1 as the first entry and also make use of any other DNS server which are deployed via the LAN's DHCP server.

If johnea/bind is not running, it does not affect the name resolution, because you will still have entries in /etc/resolv.conf.

🖤 Sister Projects

Show some love for the following sister projects.

🖤 Project	🐱 GitHub	🐋 DockerHub
	Devilbox
	docker-php-fpm	devilbox/php-fpm
	docker-php-fpm-community	devilbox/php-fpm-community
	docker-mysql	devilbox/mysql
	docker-apache-2.2 docker-apache-2.4 docker-nginx-stable docker-nginx-mainline	devilbox/apache-2.2 devilbox/apache-2.4 devilbox/nginx-stable devilbox/nginx-mainline
	docker-bind	cytopia/bind

👫 Community

In case you seek help, go and visit the community pages.

📘 Documentation	🎮 Discord	🗪 Forum
devilbox.readthedocs.io	discord/devilbox	devilbox.discourse.group

📜 Articles

• Serving Bind DNS in Kubernetes

❤️ Credits

Thanks for contributing 🖤

• @atomicbaum1
• @ericp-mrel
• @Zighy

🧘 Maintainer

@cytopia

I try to keep up with literally over 100 projects besides a full-time job. If my work is making your life easier, consider contributing. 🖤

• GitHub Sponsorship
• Patreon
• Open Collective

Findme: 🐱 cytopia / devilbox | 🐋 cytopia / devilbox | 🐦 everythingcli / devilbox | 📖 everythingcli.org

Contrib: PyPI: cytopia · Terraform: cytopia · Ansible: cytopia

🗎 License

MIT License

Copyright (c) 2022 cytopia