Command Line Daemon

DNS proxy server you can run on a router, or any other device.

In order to facilitate simple onboarding, on any type of device (with a keyboard) we've developed an open source command line daemon, known as ctrld. It can be used to configure a Control D Device with a single command, and it can do a whole bunch more.

Why Use This

You may want to use this utility in the following situations:

  • You operate a network, and have to use Legacy DNS for all your LAN clients
  • Want to use Secure DNS protocols on a device that does not support them
  • Want to create an advanced DNS routing policy
  • Want to see all your LAN clients, and create DNS policies for all of them via a web GUI (will be available in v1.2)

Download

Head over to Github, and download the version of the daemon for your platform. You can find builds for most operating systems in the Releases section.

Currently supported operating systems are:

  • Windows (386, AMD64 and ARM) - use the _windows builds
  • Mac (AMD64 and ARM) - use the _darwin builds
  • Linux (386, ARM, MIPS) - use the _linux builds
1270

Get your resolver ID

When you create a Control D Device, you are issued a set of DNS resolvers. Look at your DNS-over-HTTPS resolver. The string after the slash is your resolver ID.

ie. https://dns.controld.com/abcd1234 -> abcd1234 is the resolver ID.

Start Service

This command must be executed with admin/sudo privilege.

Windows

Open Administrative command line, and navigate to the folder where the .exe file is extracted, and run this command.

ctrld.exe start --cd abcd1234

This command will do the following:

  • Fetch your Device's configuration
  • Render a configuration file and store it in the HOME directory
  • Spawn a DNS listener and start a system service that will always run
  • Configure the DNS on the default interface to use the local DNS proxy server

MacOS

Open terminal, navigate to the folder where the binary file is extracted, and run this command.

sudo ./ctrld start --cd abcd1234

This command will do the following:

  • Fetch your Device's configuration
  • Render a configuration file and store it in the HOME directory
  • Spawn a DNS listener and start a system service that will always run
  • Configure the DNS on the default interface to use the local DNS proxy server

Linux

Open terminal, navigate to the folder where the binary file is extracted, and run this command.

sudo ./ctrld start --cd abcd1234

This command will do the following:

  • Fetch your Device's configuration
  • Render a configuration file and store it in the HOME directory
  • Spawn a DNS listener and start a system service that will always run
  • Configure the DNS on the default interface to use the local DNS proxy server

Stop Service

In order to temporarily stop the Control D service, execute the following command with admin/sudo privilege:

Windows

ctrld.exe stop

MacOS

sudo ./ctrld stop

Linux

sudo ./ctrld stop

🚧

Service is still installed

The above commands will stop the service, and unconfigure the listener it spawned from the default interface. If the system is rebooted, the original configuration will be restored automatically.

Uninstall Service

In order to permanently stop using the daemon, and unconfigure Control D so it doesn't run on machine reboot, you have to uninstall the service. This can be done one of 2 ways.

Manual

Run the following commands with admin/sudo privilege:

Windows

ctrld.exe stop
ctrld.exe service uninstall

MacOS

sudo ./ctrld stop
sudo ./ctrld service uninstall

Linux

sudo ./ctrld stop
sudo ./ctrld service uninstall

Automatic

Simply delete the associated Device from the web control panel. This will break DNS on the machine that is using this Device's resolvers.

Then simply reboot the machine. On startup, the service will self-terminate and uninstall itself.

Do More

This is the most basic use of the ctrld daemon. It can do a whole lot more, especially if you run it on a router. What can you do with it? Here are some use cases:

  1. Create unique DNS routing policies based on source IP, device hostname or MAC address
  2. Split horizon DNS with wildcard rules
  3. Use Secure DNS protocols even for devices that don't support them (UDP53-to-DOH)
  4. Run multiple DNS listeners, with unique policies and variable upstreams
  5. Cache DNS records locally

For a full feature set, please check out the README.