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 policies or leverage split horizon DNS
- Want to see all your LAN clients, and create DNS policies for all of them via a web GUI
- Want to deploy Secure DNS on a roaming client
Quick Install
The simplest way to start using ctrld
is to run the installer. Open an terminal and execute this command as admin/system user on any Linux or UNIX-like OS (including MacOS):
sh -c 'sh -c "$(curl -sL https://api.controld.com/dl)" -s RESOLVER_ID_HERE'
Template RESOLVER_ID_HERE
with your actual Resolver ID from the relevant Device.
If you'd like to use the same method on Windows, run this in admin cmd:
powershell -Command "(Invoke-WebRequest -Uri 'https://api.controld.com/dl' -UseBasicParsing).Content | Set-Content '%TEMP%\ctrld_install.bat'" && %TEMP%\ctrld_install.bat RESOLVER_ID_HERE
The above scripts will do the following:
- Detect your OS and architecture
- Present you with your system info and what it's about to do
- Once you press
y
- Download the appropriate binary
- Make it executable
- Register a system service and start the DNS server
- Modify the DNS settings on your network adapter to use the local server
In order to skip the interactive confirmation (y/n), simply append forced
flag to the installer command. ie. -s RESOLVER_ID_HERE forced
for MacOS and Linux, and RESOLVER_ID_HERE forced
for Windows + PowerShell. This will perform the installation without any user confirmation or input.
Download Manually
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, AMD64, ARM, MIPS) - use the
_linux
builds - FreeBSD (386, AMD64, ARM) - use the
_freebsd
builds
Get your resolver ID
When you create a Control D Device, you are issued a set of DNS resolvers. On the screen that shows you your resolvers, you will see "Resolver ID" at the top.
Windows
Start Service
Open Administrative command line, and navigate to the folder where the .exe file is extracted, and run this command.
ctrld.exe start --cd RESOLVER_ID_HERE
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 from Administrative command line:
ctrld.exe 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 uninstall ctrld
run this command.
ctrld.exe uninstall
ctrld
binary will remain on disk and can be used at a later time. To remove all files from disk, append --cleanup
flag to the uninstall command.
MacOS
Start Service
Open terminal, navigate to the folder where the binary file is extracted, and run this command.
sudo ctrld start --cd RESOLVER_ID_HERE
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:
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 uninstall ctrld
run this commands
sudo ctrld uninstall
ctrld
binary will remain on disk and can be used at a later time. To remove all files from disk, append --cleanup
flag to the uninstall command.
Linux
Start Service
Open terminal, navigate to the folder where the binary file is extracted, and run this command.
sudo ctrld start --cd RESOLVER_ID_HERE
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:
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 uninstall ctrld
run this command.
sudo ctrld uninstall
If you are running ctrld
on a router, you may need to run the above command from the directory where you installed it. sudo
may be optional if you're running it as a root user.
ctrld
binary will remain on disk and can be used at a later time. To remove all files from disk, append --cleanup
flag to the uninstall command.
Routers
ctrld
currently supports the following routers and firmware:
- ASUS Merlin
- DD-WRT
- Firewalla
- Fresh Tomato
- GL.iNet
- OpenWRT
- pfSense / OPNsense
- Synology
- Ubiquiti UDM, UDR, EdgeOS
All you have to do is SSH into your router and follow the Quick Install instructions at the top of this page. With a single command, you can start using Control D in literally seconds.
Remote Uninstallation
Simply delete the associated Device from the web control panel. The DNS daemon will self-uninstall if you're using v1.3.9 or newer.
Upgrade
In order to upgrade the ctrld
service to the latest version, there are two ways to do it.
- Simply re-run the installer command without any args. Use this method if you're running v1.3.7 or earlier.
- Run
ctrld upgrade
command. This is the recommended method.
Windows
Run this batch command in admin cmd (not Powershell). Use this if you're running v1.3.7 or earlier.
powershell -Command "(Invoke-WebRequest -Uri 'https://api.controld.com/dl' -UseBasicParsing).Content | Set-Content '%TEMP%\ctrld_install.bat'" && %TEMP%\ctrld_install.bat
or
ctrld upgrade
Linux or Mac
Run this bash command in Terminal as root user.
sh -c 'sh -c "$(curl -sL https://api.controld.com/dl)"'
or
ctrld upgrade
Update Channels
There are 2 update channels:
prod
- stable production release (default)dev
- beta release that is ahead of production
To switch channels, append the channel name to the upgrade command:
C:\Windows\system32>ctrld upgrade prod
Jul 22 13:21:56.000 NTC Upgrade successful - v1.3.7
C:\Windows\system32>ctrld upgrade dev
Jul 22 13:22:54.000 NTC Upgrade successful - dev-429123b
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:
- Create unique DNS routing policies based on source IP, device hostname or MAC address
- Split horizon DNS with wildcard rules
- Use Secure DNS protocols even for devices that don't support them (UDP53-to-DOH)
- Run multiple DNS listeners, with unique policies and variable upstreams
- Cache DNS records locally
For a full feature set, please check out the README.
Example Configs
Want to craft your own config? No problem, check out some examples.
Troubleshooting
Something not working? Check out the troubleshooting guide.
Updated 25 days ago