In this article
Use this guide to install and manage the DNSFilter Relay using the Relay Manager command line interface (CLI).
The DNSFilter Relay Manager CLI is a command-line utility that standardizes how the DNSFilter Relay is installed, updated, configured, and maintained across supported environments.
It supports both Docker-based deployments and binary installations, providing a consistent workflow for common lifecycle tasks such as setup, service control, log access, and troubleshooting.
Prerequisites
- A supported OS architecture:
- macOS 64 bit
- Windows 64 bit
- Linux 64 bit
- Linux arm
- Linux arm 64
- Linux mipsle
- Raspberry Pi
- Admin permissions to run
sudocommands - DNSFilter recommends using a Static IP or DHCP reservation for Relay deployment
- If running Docker mode, Docker must be installed and running
Linux configuration note (systemd-resolved)
Some Linux distributions, including Ubuntu, run the systemd-resolved service by default. This service can interfere with DNS Relay in binary deployments by binding to the system DNS stub
If the Relay installs successfully but local DNS resolution behaves unexpectedly, disable the DNS stub listener in systemd-resolved and configure the system resolver manually before starting the Relay. This prevents conflicts between the OS resolver and the Relay service.
Deployment Modes
Relay Manager supports multiple deployment modes for compatibility with both modern and legacy Relay environments.
| Mode | Config Location | Registry Location |
|---|---|---|
|
Docker Uses Docker volumes for configuration. Follow this path to copy the |
~/.relay/docker/relay.conf |
~/.relay/docker/relay.reg |
|
Binary Runs Relay directly as a local binary. Follow this path to copy the |
~/.relay/binary/relay.conf |
~/.relay/binary/relay.reg |
|
Legacy VM Matches historical VM-based installs. |
/etc/relay/relay.conf |
/etc/relay/relay.reg |
Updating an existing Relay deployment
Existing Relay deployments follow the same installation process as new deployments. Relay Manager detects a running Relay automatically during installation and adopts it into the new management system.
If Relay Manager does not detect the existing Relay during installation, remove the old Relay first, then run the installation process again.
Relays that have been replaced or removed will display as offline in the DNSFilter dashboard. Use the Delete option to remove offline Relays from the dashboard view.
Install Relay Manager and Relay
- From the DNSFilter dashboard, navigate to Deployments and select Relays
- Select Install Relay
- Select a Site to associate with the Relay
- Select the Install Command (PowerShell or Bash)
-
Copy and execute the script
The Relay Manager is now installed. Continue to install a Relay.
- Run this command in the Relay Manager:
relay-manager install- The default installation is Docker, and the manager runs logic to detect it is running and accessible. To install as Binary, add
-bto the install command, e.g.relay-manager install -b
- The default installation is Docker, and the manager runs logic to detect it is running and accessible. To install as Binary, add
- Select a new or existing Relay config file
- Enter the Site Key found in the dashboard install page
- Select a log type. Info is recommended for standard deployments
- Enter a Hostname if applicable. If nothing is entered, the device hostname will default to the DNSFilter dashboard
The Relay is now installed. Confirm by running relay-manager status to check the Relay Docker/Binary status, container, and networks are configured as expected.
Uninstall Relay Manager and Relay
Use the applicable uninstall script to remove the Relay Manager. This command stops and uninstalls the DNS Relay, removes the Relay Manager, and provides a success message when complete.
iex ((New-Object System.Net.WebClient).DownloadString('https://download.dnsfilter.com/Relay/manager-uninstall.ps1'))curl -sS https://download.dnsfilter.com/Relay/manager-uninstall.sh | sudo bash
The Relay will move to offline status in the dashboard. Use the Delete option to remove the offline Relay.
Uninstall DNS Relay only
The DNS Relay can be uninstalled without removing the Relay Manager by using the uninstall command. Add -a for advanced uninstall steps.
Troubleshooting with Relay Manager
Use the Relay Manager to run built-in health checks and diagnostics.
From the command line, run these 3 commands in order:
relay-manager statusrelay-manager logsrelay-manager troubleshoot
These commands perform basic checks and provide guidance where possible. If the issue persists, submit both the troubleshoot output and the generated logs in a Support Request so the team can investigate further.
Configure log output
By default, the Relay outputs logs to the console only. On binary deployments where no console is attached—such as a Windows service—no log file is created unless explicitly configured.
To write logs to a file, add a file key under the [log] section of relay.conf:
[log] # Console error log, defaults to "error" level = "info" file = "relay.log"
The file value can be a filename (saved to the default Relay directory) or a full file path. Once enabled, the Relay automatically rotates log files, retaining up to 10 files with a maximum of 100MB total.
After editing relay.conf, restart the Relay for changes to take effect:
relay-manager stop relay-manager start
Related Content
- Relay Manager commands to help configure, update, and maintain DNS Relays
- Navigating the DNS Relay dashboard
Comments
8 comments
If I already have a relay.conf file in a directory, how do I edit the config to load the relay.conf into the new installation? Is there a directory I should copy the relay.conf file?
UPDATE: I was able to copy it to /root/.relay/binary and it loaded the relay.conf.
Kudos for developing this. It makes it much easier to maintain the relay! Love the options to simply run an update with relay-manager instead of needing to manually copy the relay, edit permissions, etc. Great job DNSFilter team!
Thanks for the kind words, Eric Nix! The team is really proud of this one, so glad you're enjoying it so far—I passed along your message to the whole company 💖
And…you found a bug 🐛 😅
The expected behavior for the Relay Manager should be a bit more intuitive than what you discovered, so the team has a ticket in to address it in the next version release. I'll update this article once the fix releases.
In the meantime, I’ve updated the article to note how to copy an existing
relay.confuntil the fix is implemented. Thanks for making our customer experience better![root@perfecthost bin]# ./relay-manager config editFailed to edit config: exec: "nano": executable file not found in $PATHI'm pretty sure that none of ed, nano, nor emacs are installed on this host.
Please don't add ‘dnf -y nano’ to the hack installer, but please simply detect editors and let us choose if there are more than one available.
Hi T , thanks for the feedback! Totally understand where you're coming from, so I went ahead and added the feature request on your behalf. Feel free to comment there if I missed anything!
If we are putting this on a server that already has the old relay running, will the relay-manager remove the old entry from systemd and shut it down or do we need to do that manually first? This article sounds like the expectation is to do a clean install. That's fine for Docker people but what about those of us running the binary directly inside a real metal linux install? If we need to first remove the old systemd entry and delete relay-linux-amd64, you should put a note with a link to the old article for people who set it up long enough ago that they forgot how they did it. :)
Great question, Admin! No need to shut down the existing relay first—if you copy the existing binary into the Relay Manager, it'll take over for the existing deployment. We list the pathways to copy the existing relay .conf to help jog your memory 😉
If you run into any snags along the way, drop a comment here and we'll get you sorted. 🙌
It didn't go exactly smoothly. Just out of curiosity, I left the old one in place and ran the script, then `relay-manager install` to see what would happen. When I told it I wanted to use an existing relay.conf in a custom path it didn't seem to let me tell it where to look, but looked for itself and failed to find. Checking status showed no config. At that point, I stopped the old relay using systemctl and then reran the install and acted like it was a fresh install, then edited the config it created. After that, status said the binary in /root/.relay/binary was not running so I edited the old systemd service config file to point to the new path, then had systemd reload all the modules. Finally, it was running and I was able to test it.
So, from my experience it is best to first stop and disable the old systemd entry, run the script, then run relay-manager to install, then edit the config it creates or copy the old one over top of it and reload everything, then edit the systemd entry to point to the new path, then enable that again. On our second relay, even after doing this, the status still said the proper binary wasn't running and it took another run of the install through relay-manager to get the proper binary running. Very odd but we got there. Note that this is all on Kubuntu 24.04, not straight debian, so I don't know if that was part of the issue with a different version of systemd. Also, the relay-manager install should be checking for an existing dnsfrelay.service and editing the path in there to make it smoother.
Honestly, the instructions should probably just tell people who want to replace an old install to refer to the old deploy instructions and undo everything they did with systemd to make sure the old one is no longer running or existent before running these steps above. Then they can stop the service using relay-manager, move the old config into place, then start it back up.
Thanks for the detailed writeup, Admin—and glad you got both relays up and running, even if the road was a little bumpier than expected!
Your experience is really helpful feedback, and the edge cases you hit around the config path handling and systemd service updates are things we'll be looking into with our engineering team. The Kubuntu note is a good catch too.
In the meantime, if anyone else lands here mid-migration and gets stuck, the
relay-manager status,relay-manager logs, andrelay-manager troubleshootcommands are your best friends for figuring out what's going on. 🛠️**Open a Support Ticket** with these outputs and the team can help get you fixed up!
Please sign in to leave a comment.