controldns/ctrld repository overview

⁠ctrld / Control D

A highly configurable DNS forwarding proxy with support for:

• Multiple listeners for incoming queries
• Multiple upstreams with fallbacks
• Multiple network policy driven DNS query steering
• Policy driven domain based "split horizon" DNS with wildcard support
• Integrations with common router vendors and firmware
• LAN client discovery via DHCP, mDNS, and ARP

⁠TLDR

Proxy legacy DNS traffic to secure DNS upstreams in highly configurable ways. All DNS protocols are supported, including:

• UDP 53
• DNS-over-HTTPS
• DNS-over-TLS
• DNS-over-HTTP/3 (DOH3)
• DNS-over-QUIC

⁠Use Cases

1. Use secure DNS protocols on networks and devices that don't natively support them (legacy routers, legacy OSes, TVs, smart toasters).
2. Create source IP based DNS routing policies with variable secure DNS upstreams. Subnet 1 (admin) uses upstream resolver A, while Subnet 2 (employee) uses upstream resolver B.
3. Create destination IP based DNS routing policies with variable secure DNS upstreams. Listener 1 uses upstream resolver C, while Listener 2 uses upstream resolver D.
4. Create domain level "split horizon" DNS routing policies to send internal domains (*.company.int) to a local DNS server, while everything else goes to another upstream.
5. Deploy on a router and create LAN client specific DNS routing policies from a web GUI (When using ControlD.com).

⁠Usage

The cli is self documenting, so free free to run --help on any sub-command to get specific usages.

⁠Pull Container

docker pull controldns/ctrld:latest

⁠Run Container

This will generate a default config and start the container. You can then edit ctrld.toml to suit your needs. View full documentation⁠ on Github.

docker run -d --name=ctrld -p 127.0.0.1:53:53/tcp -p 127.0.0.1:53:53/udp controldns/ctrld:latest -vv

Alternatively, you can supply a --cd flag with your own Control D Resolver ID.

docker run -d --name=ctrld -p 127.0.0.1:53:53/tcp -p 127.0.0.1:53:53/udp controldns/ctrld:latest --cd=RESOLVER_ID_GOES_HERE -vv

⁠Invoke Binary

docker run --rm -it --entrypoint=/ctrld controldns/ctrld:latest
        __         .__       .___
  _____/  |________|  |    __| _/
_/ ___\   __\_  __ \  |   / __ |
\  \___|  |  |  | \/  |__/ /_/ |
 \___  >__|  |__|  |____/\____ |
     \/ dns forwarding proxy  \/

Usage:
  ctrld [command]

Available Commands:
  run         Run the DNS proxy server
  service     Manage ctrld service
  start       Quick start service and configure DNS on interface
  stop        Quick stop service and remove DNS from interface
  restart     Restart the ctrld service
  status      Show status of the ctrld service
  uninstall   Stop and uninstall the ctrld service
  clients     Manage clients

Flags:
  -h, --help            help for ctrld
  -s, --silent          do not write any log output
  -v, --verbose count   verbose log output, "-v" basic logging, "-vv" debug level logging
      --version         version for ctrld

Use "ctrld [command] --help" for more information about a command.