Public | Automated Build

Last pushed: a year ago
Short Description
docker auto discovery dns
Full Description


DNS server for automatic docker container discovery. Simplified version of

This project was initially created and maintained by tonistiigi.

Differences from skydock

  • No raft / simple in-memory storage - Does not use any distributed storage
    and is meant to be used only inside single host. This means no ever-growing
    log files and memory leakage. AFAIK skydock currently does not have a state
    machine so the raft log always keeps growing and you have to recreate the
    server periodically if you wish to run it for a long period of time. Also the
    startup is very slow because it has to read in all the previous log files.

  • No TTL heartbeat - Skydock sends heartbeats for every container that reset
    the DNS TTL value. In production this has not turned out to be reliable. What
    makes this worse it that if a heartbeat has been missed, skydock does not
    recover until you restart it. Dnsdock uses static TTL that does not count down.
    You can override it for a container and also change it without
    restarting(before updates). In most cases you would want to use TTL=0 anyway.

  • No dependency to other container - Dnsdock does not use a separate DNS
    server but has one built in. Linking to another container makes recovery from
    crash much harder. For example skydock does not recover from skydns crash even
    if the crashed container is restarted.

  • A records only for now.

  • No support for Javascript plugins.

  • There's a slight difference in a way image names are extracted from a
    container. Skydock uses the last tag set on image while dnsdock uses the
    specific tag that was used when the container was created. This means that if a
    new version of an image comes out and untags the image that your container
    still uses, the DNS requests for this old container still work.


Building without docker:

Install a golang development environment on your host and type the following commands:

export GOPATH=/tmp/go
export PATH=${PATH}:${GOPATH}/bin
go get -v
go get -d -v
cd ${GOPATH}/src/
godep restore
cd ${GOPATH}/src/
go build -o ${GOPATH}/bin/dnsdock
Building with docker:

To build with docker you need rocker. Check the
website to install it and type the following commands:

git clone <clone_directory_path>
rocker build -var ARCH=[amd64|arm] -var OUTPUT_DIR=<outputdir> <clone_directory_path>


Dnsdock connects to Docker Remote API and keeps an up to date list of running
containers. If a DNS request matches some of the containers their local IP
addresses are returned.

Format for a request matching a container is:

  • environment and domain are static suffixes that are set on startup. Defaults to docker.
  • image-name is last part of the image tag used when starting the container.
  • container-name alphanumerical part of container name.

You can always leave out parts from the left side. If multiple containers match
then they are all returned. Wildcard requests are also supported.

> dig *.docker
docker.            0    IN    A
docker.            0    IN    A
docker.            0    IN    A
docker.            0    IN    A

> dig redis.docker
redis.docker.        0    IN    A
redis.docker.        0    IN    A

> dig redis1.redis.docker
redis1.redis.docker.        0    IN    A

> dig redis1.*.docker
redis1.*.docker.        0    IN    A


DNS listening port needs to be bound to the docker0 inferface so that its
available to all containers. To avoid this IP changing during host restart add
it to the docker default options.

  • If you use systemd (present on Fedora and recent Ubuntu versions), edit
    /lib/systemd/system/docker.service and add the options to the command you
    will see in the ExecStart section, the run sudo systemctl daemon-reload.
  • If you do not, Open file /etc/default/docker and add --bip= --dns= to DOCKER_OPTS variable.

Restart docker daemon after you have done that (sudo service docker restart).

Now you only need to run the dnsdock container:

docker run -d -v /var/run/docker.sock:/var/run/docker.sock --name dnsdock -p aacebedo/dnsdock [--opts]
  • -d starts container as daemon
  • -v /var/run/docker.sock:/var/run/docker.sock shares the docker socket to
    the container so that dnsdock can connect to the Docker API.
  • -p exposes the default DNS port to the docker0 bridge interface.

Additional configuration options to dnsdock command:

--dns=":53": Listen DNS requests on this address
--docker="unix://var/run/docker.sock": Path to the docker socket
--domain="docker": Domain that is appended to all requests
--environment="": Optional context before domain suffix
--help: Show this message
--http=":80": Listen HTTP requests on this address
--nameserver="": DNS server for unmatched requests
--ttl=0: TTL for matched requests
--verbose: Verbose output
--tlsverify: enable mutual TLS between dnsdock and Docker
--tlscacert="$HOME/.docker/ca.pem": Path to CA certificate
--tlscert="$HOME/.docker/cert.pem": Path to client certificate
--tlskey="$HOME/.docker/key.pem": Path to client certificate private key
--all: Process all container even if they are stopped
--forcettl: Change TTL value of responses coming from remote servers 

If you also want to let the host machine discover the containers add nameserver to your /etc/resolv.conf.

SELinux and Fedora / RHEL / CentOS

Mounting docker daemon's unix socket may not work with default configuration on
these platforms. Please use
selinux-dockersock to fix this.
More information in #11.

TLS Authentication

Instead of connecting to the Docker daemon's UNIX socket, you may prefer to
connect via a TLS-protected TCP socket (for example, if you are running Swarm).
The -tlsverify option enables TLS, and the three additional options
(-tlscacert, -tlscert and -tlskey) must also be specified. Alternatively,
you may set the DOCKER_TLS_VERIFY environment variable to a non-empty value
and the DOCKER_CERTS to a directory containing files named ca.pem,
cert.pem and key.pem.

You may build this into your own container with this example Dockerfile:

FROM aacebedo/dnsdock


CMD ["-docker=tcp://"]

Use a volume (-v /path/to/certs:/certs) to give the container access to the
certificate files, or build the certificates into the image if you have access
to a secure private image registry.

HTTP Server

For easy overview and manual control dnsdock also includes HTTP server that
lets you configure the server using a JSON API.

# show all active services
curl http://dnsdock.docker/services

# show a service
curl http://dnsdock.docker/services/serviceid

# add new service manually
curl http://dnsdock.docker/services/newid -X PUT --data-ascii '{"name": "foo", "image": "bar", "ip": "", "ttl": 30}'

# remove a service
curl http://dnsdock.docker/services/serviceid -X DELETE

# change a property of an existing service
curl http://dnsdock.docker/services/serviceid -X PATCH --data-ascii '{"ttl": 0}'

# set new default TTL value
curl http://dnsdock.docker/set/ttl -X PUT --data-ascii '10'


If you wish to fine tune the DNS response addresses you can define specific
environment variables during container startup. This overrides the default
matching scheme from container and image name.


docker run -e DNSDOCK_NAME=master -e DNSDOCK_IMAGE=mysql -e DNSDOCK_TTL=10 \
           --name mymysql mysqlimage
# matches master.mysql.docker
docker run -e DNSDOCK_ALIAS=db.docker,sql.docker -e DNSDOCK_TTL=10 \
           --name mymysql mysqlimage
# matches db.docker and sql.docker

Overrides with docker labels

If you wish to fine tune the DNS response addresses you can define specific labels during
container creation. This overrides the default matching scheme from container and image name.

Supported labels are com.dnsdock.ignore, com.dnsdock.alias,, com.dnsdock.tags, com.dnsdock.image,
com.dnsdock.ttl, com.dnsdock.region, and com.dnsdock.ip_addr

docker run -l -l com.dnsdocker.image=mysql -l com.dnsdock.ttl=10 \
           --name mymysql mysqlimage
# matches master.mysql.docker
docker run -l com.dnsdock.alias=db.docker,sql.docker -l com.dnsdock.ttl=10 \
           --name mymysql mysqlimage
# matches db.docker and sql.docker

Service metadata syntax by progrium/registrator is also supported.

docker run -l com.dnsdock.tags=master -l -l com.dnsdock.region=us2 \
           --name mymysql mysqlimage
# matches master.mysql.us2.docker

If you want dnsdock to skip processing a specific container set its
com.dnsdock.ignore label.

You can force the value of the IP address returned in the DNS record with the
com.dnsdock.ip_addr label. This can be useful if you have a reverse proxy such as traefik in a container with mapped port and you want to redirect your clients to the front server instead of an internal docker container ip address.

OSX Usage

Original tutorial:

If you use docker on OSX via Vagrant you can do this to make your containers
discoverable from your main machine.

In your Vagrantfile add the following to let your virtual machine accept
packets for other IPs:

config.vm.provider :virtualbox do |vb|
  vb.customize ["modifyvm", :id, "--nicpromisc2", "allow-all"]

Then route traffic that matches you containers to your virtual machine internal IP:

sudo route -n add -net <VAGRANT_MACHINE_IP>

Finally, to make OSX use dnsdock for requests that match your domain suffix
create a file with your domain ending under /etc/resolver (for example
/etc/resolver/myprojectname.docker) and set its contents to nameserver

coreos-vagrant usage

You can autostart the dnsdock service in the user-data file of coreos-vagrant.
Everytime you vagrant up this CoreOs vagrant instance the dnsdock service
will be running and start discovering your other services.

Add the following snippet under the units part:

- name: dnsdock.service
      enable: true
      command: start
      content: |

        ExecStartPre=/bin/sh -c '/usr/bin/docker rm -f dnsdock || ls > /dev/null'
        ExecStartPre=/bin/sh -c '/usr/bin/docker pull aacebedo/dnsdock'
        ExecStart=/usr/bin/docker run -v /var/run/docker.sock:/var/run/docker.sock --name dnsdock -p ${COREOS_PRIVATE_IPV4}:53:53/udp aacebedo/dnsdock
        ExecStop=/bin/sh -c '/usr/bin/docker stop dnsdock  || ls > /dev/null'

Lots of code in this repo is directly influenced by skydns and skydock. Many thanks to the authors of these projects.

Docker Pull Command
Source Repository