Docker DNS Resolver

The Problem: Docker Networking Challenges

Imagine managing multiple containers, each with dynamic IP addresses. Connecting to them from your host or between containers becomes cumbersome, often requiring docker inspect just to find an IP. This challenge scales with your environment.

The core issue is the disconnect between human-readable container names and machine-level IP addresses. Remembering IPs is unintuitive, host access via ports is inconvenient, and inter-container communication using IPs introduces fragility.

The Solution: docker-dns

docker-dns is a lightweight yet powerful DNS server engineered to streamline networking within Docker environments. It acts as an intelligent translator, automatically resolving your Docker container names to their respective IP addresses.

This enables seamless networking not just between containers but also between containers and your host machine. Access containers using their names (e.g., http://my-site.docker) instead of grappling with IPs, making local development feel natural and efficient. This tool is invaluable for developers building and testing in Docker and DevOps engineers managing local environments.

Key Features

docker-dns offers features designed to simplify your Docker networking:

• Automatic DNS Resolution:
  • Monitors Docker events (container start/stop).
  • Registers container names and IPs automatically.
  • Uses a custom TLD (default: .docker). Example: A container named database becomes database.docker.
  • Access web apps easily: http://my-site.docker or http://my-site.docker:3000.
  • Eliminates manual IP tracking and /etc/hosts edits by dynamically updating DNS records.
• Caching Mechanism:
  • Improves performance with a configurable cache TTL (default: 300s / 5 minutes).
  • Serves subsequent requests for the same name from the cache within the TTL period.
  • Allows tuning: shorter TTL for dynamic environments (accuracy), longer TTL for stable ones (performance).
• Simple Configuration:
  • Minimal setup required.
  • Configure via command-line options or a configuration file (/etc/docker-dns/docker-dns.conf).
  • Manage settings like listening IP, TTL, TLD, and fallback DNS servers.
• Debian Package:
  • Convenient .deb package for easy installation on Debian/Ubuntu.
  • Handles dependencies and system integration automatically.
• Fallback DNS:
  • Acts as a complete DNS server for the host.
  • Forwards non-Docker domain queries (e.g., google.com) to configurable fallback DNS servers (default: Google DNS 8.8.8.8, 8.8.4.4; Cloudflare DNS 1.1.1.1).
  • Allows using docker-dns as the primary DNS server for your machine, handling both internal and external lookups.
• Lightweight and Fast:
  • Built with Go for efficiency and speed.
  • Low resource consumption (CPU/memory).
  • Delivers fast, responsive DNS resolution.

Installation and Integration (Debian/Ubuntu)

Installing docker-dns on Linux/Debian systems is straightforward:

1. Download and Install

Use the provided script to get the latest .deb package:

wget https://raw.githubusercontent.com/MedUnes/docker-dns/master/install_debian_latest.sh && \
chmod +x install_debian_latest.sh && \
./install_debian_latest.sh && \
rm install_debian_latest.sh

2. Setup & Integration Details

• The package automatically detects your system's DNS resolver (e.g., systemd-resolved, dnsmasq, unbound, plain /etc/resolv.conf).
• During interactive installation, it prompts for integration confirmation.
• Uses safe drop-in configuration files (no core system file modification).
• Restarts the DNS subsystem only if necessary.
• Backs up modified configuration files to /var/lib/docker-dns/backup.

3. Integration Modes

• systemd-resolved: Adds a drop-in config (/etc/systemd/resolved.conf.d/) to forward .docker TLD queries to 127.0.0.153. Optionally disables DHCP DNS injection. (Note: Creates symlink /etc/resolv.conf -> /run/systemd/resolve/stub-resolv.conf. See systemd-resolved docs and ArchWiki).
• dnsmasq: Appends server=/.docker/127.0.0.153 (or similar) to a config file in /etc/dnsmasq.d/.
• unbound: Adds a stub-zone block to a config file in /etc/unbound/unbound.d/ delegating .docker to docker-dns.
• Plain resolv.conf: Adds nameserver 127.0.0.153 to /etc/resolv.conf, making docker-dns the primary DNS server.

4. Rollback

Remove the service but keep configs:

sudo dpkg -r docker-dns

Completely remove docker-dns and restore previous DNS settings:

sudo dpkg -P docker-dns

Configuration

Tailor docker-dns to your needs:

1. Check Service Status

systemctl status docker-dns

2. Edit Configuration (Optional)

Primary config file: /etc/docker-dns/docker-dns.conf (INI format)

Options:

• IP: Defines the listening IP address. Default 127.0.0.153 is in the loopback range. Change if the IP is in use or you need to listen on a specific interface.
• TTL: Sets cache duration. Higher TTL = better performance (stable IPs); Lower TTL = better accuracy (dynamic IPs).
• TLD: Specifies the TLD for container resolution (e.g., mycontainer.local if TLD=local).
• DEFAULT_RESOLVER: Comma-separated list of fallback DNS servers for non-.docker queries. Customize with your preferred resolvers (ISP DNS, Pi-Hole, etc.). Provides redundancy.

3. Restart Service After Changes

sudo systemctl restart docker-dns

Practical Use Cases

• Web Browser Access: Easily access web apps in containers. Navigate to http://my-app.docker (port 80) or http://my-app.docker:3000 (port 3000).
• Resolve Container by Name (CLI): Verify resolution using dig.

  # Query docker-dns directly for the IP of container 'web'
  dig web.docker @127.0.0.153 +short

• Resolve External Domains (CLI): docker-dns forwards non-Docker queries.

  # Query docker-dns for google.com (will be forwarded)
  dig google.com @127.0.0.153 +short

• Local Development Environments: Simplify communication between multi-container setups (e.g., frontend, backend, database) using names like backend.docker, database.docker.
• Testing and Staging: Create more realistic local test environments mirroring production DNS behavior.
• Internal Tools: Access internal Dockerized tools using memorable names.
• Microservices Architectures (Local): Lightweight local service discovery for microservices using names like service-a.docker.
• Homelab Setups: Access self-hosted services (Plex, Nextcloud, etc.) in Docker using names like plex.docker, nextcloud.docker by pointing your network DNS to the docker-dns host.

Why Use docker-dns?

Security Considerations

• Local Focus: Designed primarily for local development machines.
• Minimal Permissions: Typically operates with permissions needed to talk to the Docker daemon and manage local DNS, often without root.
• Limited Data Exposure: Handles internal Docker network info (names, IPs), not sensitive host data.
• Safe Integration: Uses drop-in configs, avoiding core system file modification.
• Fallback DNS Security: Relies on the trustworthiness of your configured fallback DNS providers. Choose reputable ones.
• Open Source: Code is publicly available on GitHub for review and audit, fostering transparency and community security contributions.

docker-dns in the Real World

• Integration with Docker Compose: Services defined in docker-compose.yml can communicate using service-name.docker (e.g., web.docker), simplifying multi-container app development.
• CI/CD Pipelines (Local Testing): Enables consistent name resolution for more reliable local test suites.
• Working with Multiple Docker Networks: Can potentially be configured to resolve names across different user-defined Docker networks.
• Comparison with --link (Legacy): docker-dns offers a more robust, flexible, and modern DNS-based solution compared to the limited, legacy --link feature.

What Makes docker-dns Unique?

• Ease of Use & Integration: Simple installation (.deb package) and automatic resolver integration.
• Lightweight & Performance-Focused: Built with Go for speed and low resource usage.
• Flexibility & Configurability: Balances simplicity with options (IP, TTL, TLD, Fallback DNS).
• Comprehensive Solution: Handles both Docker container resolution and standard internet DNS lookups.

Comparison with Alternatives:

• Manual /etc/hosts: docker-dns is automated and dynamic.
• Full DNS Servers (BIND, CoreDNS): docker-dns is simpler and specifically targeted for local Docker use.
• Docker Embedded DNS: docker-dns extends resolution to the host machine using a custom TLD, which Docker's embedded DNS doesn't do by default for host access.
• Other Tools (e.g., devdns, ldhdns, docker-discover): docker-dns aims for broad resolver compatibility, ease of use (especially via .deb), and a focused, lightweight approach without extra dependencies like proxies or etcd.

Contributing

Interested in building from source or contributing?

1. Build

git clone https://github.com/medunes/docker-dns.git
cd docker-dns
make build

2. Run (after build)

sudo ./docker-dns &

Contributions (pull requests, issues) are welcome on the GitHub repository.

License

This project is licensed under the AGPL License. See the LICENSE file for details.