Skip to main content

How can we help you?

Search

help Knowledge Base
forum Community
checklist Release Notes
event Events

DNS Relay v1.4.0 or higher deployment guide

Minetta Gould
  • Updated

    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 sudo commands 
  • 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.conf file to reuse during update.

 ~/.relay/docker/relay.conf ~/.relay/docker/relay.reg

Binary

Runs Relay directly as a local binary. 

Follow this path to copy the relay.conf file to reuse during update.

 ~/.relay/binary/relay.conf ~/.relay/binary/relay.reg

Legacy VM

Matches historical VM-based installs.

 /etc/relay/relay.conf /etc/relay/relay.reg

Install Relay Manager and Relay

  1. From the DNSFilter dashboard, navigate to Deployments and select Relays
  2. Select Install Relay
  3. Select a Site to associate with the Relay
  4. Select the Install Command (PowerShell or Bash)

  5. Copy and execute the script

    The Relay Manager is now installed. Continue to install a Relay.

  6. Run this command in the Relay Manager: relay-manager install
    1. The default installation is Docker, and the manager runs logic to detect it is running and accessible. To install as Binary, add -b to the install command, e.g. relay-manager install -b
  7. Select a new or existing Relay config file
  8. Enter the Site Key found in the dashboard install page
  9. Select a log type. Info is recommended for standard deployments
  10. 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://s3.amazonaws.com/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 status

  • relay-manager logs

  • relay-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.

Related Content

Comments

2 comments

Date Votes
  • Eric Nix
    • Edited
    Active Contributor

    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!

    0
  • Minetta Gould Community Team DNSFilter Staff

    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.conf until the fix is implemented. Thanks for making our customer experience better!  

    1

Please sign in to leave a comment.