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
      12. ALLOW_QUERY
      13. ALLOW_RECURSION
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
   8. Extra hosts, DNS resolver, allow query, and allow recursion
5. Host integration
6. Support
7. License

Environmental variables

Required environmental variables

• None

Optional environmental variables

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

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'

Default mount points

• None

Default ports

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

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 EXTRA_HOSTS='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 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