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

Deployment Modes

Relay Manager supports multiple deployment modes for compatibility with both modern and legacy Relay environments.

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. 

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

• Relay Manager commands to help configure, update, and maintain DNS Relays
• Navigating the DNS Relay dashboard