bhanditz / docker-bind

Bind caching DNS server on Debian with wild-card domain support

Bind Docker

---

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

Docker Hub	Upstream Project

---

Table of Contents

1. Environmental variables
   1. Required environmental variables
   2. Optional environmental variables
      1. DEBUG_ENTRYPOINT
      2. DOCKER_LOGS
      3. WILDCARD_DNS
      4. EXTRA_HOSTS
      5. DNSSEC_VALIDATE
      6. DNS_FORWARDER
      7. TTL_TIME
      8. REFRESH_TIME
      9. RETRY_TIME
      10. EXPIRY_TIME
      11. MAX_CACHE_TIME
2. Default mountpoints
3. Default 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
5. Host integration
6. Support
7. License

---

Environmental variables

Required environmental variables

• None

Optional environmental variables

Variable	Type	Default	Description
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.
WILDCARD_DNS	string		Add one or more tld's, domains or subdomains as catch-all for a specific IP address or CNAME. Reverse DNS is optional and can also be specified.
EXTRA_HOSTS	string		Add one or more hosts (CNAME: tld's, domains, subdomains) to map to a specific IP address or CNAME. Reverse DNS is optional and can also be specified.
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
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

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

WILDCARD_DNS

The WILDCARD_DNS option allows you to specify one or more multiple catch-all DNS zones which can either be a full TLD, a domain or any kind of subdomain. It allows you to map your catch-all to a specific IP address or even a CNAME (if it is resolvable by public DNS servers). Optionally you can also assign the reverse DNS name (PTR record).

The general format is as follows, whereas the string in square brackets it optional and responsible for the reverse DNS (PTR records):

# Structure
WILDCARD_DNS='tld1=1.1.1.1[=tld],tld2=2.2.2.2[=tld2]'
WILDCARD_DNS='tld1=CNAME1[=tld],tld2=CNAME2[=tld2]'

Some examples:

# 1. One entry:
# The following catches all queries to *.tld and redirects them to 192.168.0.1
WILDCARD_DNS='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
WILDCARD_DNS='tld=192.168.0.1,example.org=192.168.0.2'

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

# 4. Adding reverse DNS:
# The following catches all queries to *.tld and redirects them to 192.168.0.1
# As well as adding reverse DNS from 192.168.0.1 to resolve to tld
WILDCARD_DNS='tld=192.168.0.1=tld'

# 5. Complex example
# The following catches all queries to *.tld and redirects them to whatever
# IP example.org resolved to. Additionally it adds a reverse DNS record from example.org's
# IP to resolve to tld (PTR record)
# It also adds another catch-all for the subdomain of *.cytopia.tld which will point to 192.168.0.1
# Including a reverse DNS record back to cytopia.tld
WILDCARD_DNS='tld=example.org=tld,cytopia.tld=192.168.0.1=cytopia.tld'

EXTRA_HOSTS

The EXTRA_HOSTS option almost works like the WILDCARD_DNS option, except that no wildcard is added, but rather exactly the host you have specified.

This is useful if you want to add extra hosts to your setup just like the Docker Compose option extra_hosts

# Structure
EXTRA_HOSTS='host1=1.1.1.1[=host1],host2=2.2.2.2[=host2]'
EXTRA_HOSTS='host1=CNAME1[=host1],host2=CNAME2[=host2]'

Some examples:

# 1. One entry:
# The following extra host 'tld' is added and will always point to 192.168.0.1.
# When reverse resolving '192.168.0.1' it will answer with 'tld'.
EXTRA_HOSTS='tld=192.168.0.1'

# 2. One entry:
# The following extra host 'my.host' is added and will always point to 192.168.0.1.
# When reverse resolving '192.168.0.1' it will answer with 'my.host'.
EXTRA_HOSTS='my.host=192.168.0.1'

# 3. Two entries:
# The following extra host 'tld' is added and will always point to 192.168.0.1.
# When reverse resolving '192.168.0.1' it will answer with 'tld'.
# A second extra host 'example.org' is added and always redirects to 192.168.0.2
# When reverse resolving '192.168.0.2' it will answer with 'example.org'.
EXTRA_HOSTS='tld=192.168.0.1,example.org=192.168.0.2'

# 4. Using CNAME's for resolving:
# The following extra host 'my.host' is added and will always point to whatever
# IP example.org resolves to.
# When reverse resolving '192.168.0.1' it will answer with 'my.host'.
EXTRA_HOSTS='my.host=example.org'

# 5. Adding reverse DNS:
# The following extra host 'my.host' is added and will always point to whatever
# IP example.org resolves to.
# As well as adding reverse DNS from 192.168.0.1 to resolve to tld
EXTRA_HOSTS='tld=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'

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

Default mount points

• None

Default 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 cytopia/bind

Wildcard domain

Let's add a wildcard zone for *.example.com. All subdomains as well as the main domain will resolve to 192.168.0.1.

$ docker run -i \
    -p 53:53/tcp \
    -p 53:53/udp \
    -e WILDCARD_DNS='example.com=192.168.0.1' \
    -t cytopia/bind

Wildcard subdomain

Let's add a wildcard zone for *.aws.example.com. All subdomains as well as the main subdomain will resolve to 192.168.0.1.

$ docker run -i \
    -p 53:53/tcp \
    -p 53:53/udp \
    -e WILDCARD_DNS='aws.example.com=192.168.0.1' \
    -t cytopia/bind

Wildcard TLD

Let's add a wildcard zone for *.loc. All domains, subdomain as well as the TLD itself will resolve to 192.168.0.4.

$ docker run -i \
    -p 53:53/tcp \
    -p 53:53/udp \
    -e WILDCARD_DNS='loc=192.168.0.4' \
    -t cytopia/bind

Wildcard TLD and reverse DNS entry

Let's add a wildcard zone for *.loc. All domains, subdomain as well as the TLD 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 WILDCARD_DNS='loc=192.168.0.4=host.loc' \
    -t cytopia/bind

Wildcard TLD and DNS resolver

Let's add a wildcard zone for *.loc. All domains, subdomain as well as the TLD 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 WILDCARD_DNS='loc=192.168.0.1' \
    -e DNS_FORWARDER=10.0.15.1,10.0.15.2 \
    -t cytopia/bind

Wildcard TLD, DNS resolver and extra hosts

• 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
• Also add two extra hosts with custom DNS:
  • host5.loc -> 192.168.0.2
  • host5.org -> 192.168.0.3

$ docker run -i \
    -p 53:53/tcp \
    -p 53:53/udp \
    -e WILDCARD_DNS='loc=192.168.0.1' \
    -e EXTRA_HOSTS='host5.loc=192.168.0.2,host5.org=192.168.0.3' \
    -e DNS_FORWARDER=10.0.15.1,10.0.15.2 \
    -t cytopia/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 cytopia/bind is not running, it does not affect the name resolution, because you will still have entries in /etc/resolv.conf.

Support

If you need support, join the Gitter Chat:

License

MIT License

Copyright (c) 2016 cytopia