In this article

This article outlines how to deploy a DNS Relay using binary with an in-app generated configuration or manual configuration. This article also includes links to deployment instructions for Relay Images and Docker.  

The DNSFilter Relay provides organizations greater visibility of DNS traffic on their network by performing split-horizon DNS resolution. The DNSFilter Relay determines if the request matches a domain that is designated as local—sending the request to the LAN DNS server—or tags the request with information that identifies the client (ipv4 address) and sends the traffic to DNSFilter.

See our deployment options guide for more Relay details. 

The DNS Relay binary is available via in-app download for these OS architectures:

• macOS 64 bit
• Windows 64 bit
• Linux 64 bit
• Linux arm
• Linux arm 64
• Linux mipsle

DNSFilter recommends using a Static IP or DHCP reservation for Relay deployment.

Deployment Notes

• Windows Users: Add a task schedule to launch the Relay at device startup to avoid filtering disruption when devices reboot.  
• If you ever need to update Local Domains or Resolvers, make the updates to the relay.conf file, not the dashboard, and restart the Relay to apply the changes.

Generated config file deployment (default)

From the DNSFilter dashboard admins can generate a config file that automatically contains the Site Secret Key, preferred Log Level, Hostname, and Local Domains/Resolvers to speed up the deployment process: no file edits required!

Follow these steps to complete the installation after creating a Site to associate with the Relay.

1. From the DNSFilter dashboard, navigate to Deployments and select Relays
2. Tab to Install
3. The Install page defaults to Generated under Select Configuration Method
4. Select a Site to associate with the Relay
5. Select the Log Level
   1. Log Error Only: Minimal logging for non-fatal errors in the relay (level = 'error')
   2. Log Errors & Troubleshooting Details: (Recommended) Includes information regarding relay state that is useful for support team troubleshooting (level = 'info')
   3. Log Everything: Detailed information regarding relay state, events, and activity. Logs will take up more space due to logging routed queries (level = 'debug')
6. Enter a Hostname (optional)
   ✍️ This step is helpful when deploying Relays to specific devices
7. Add Local Domains and Local Resolvers (optional)
8. Select Download to download the config file 
9. Under Install, download the Relay executable file (labeled DNSFilter for Windows/macOS/Linux)

Continue below to Step three: Run the executable file to complete the installation process. 

Manual config file deployment

Note that single-line settings/parameters (such as upstream_order) must be placed before the [xyz] TOML Tables: it cannot be placed at the bottom of the file or it will automatically become part of the last TOML Table.

Step one: Create an associated Site

1. Create a new Site to associate with the Relay
2. From the DNSFilter dashboard, navigate to Deployments and select Relays
3. Tab to Install
4. Toggle Select Configuration Method to Manual
5. Select the Site

Step two: Download the Configuration and Relay files

Once a Site is selected, the app generates a Secret Key for the config file. Use this Secret Key to edit the config file.

1. From the same page in the DNSFilter dashboard, download the sample configuration file
2. Open the file and edit these fields:
   1. secret_key: Enter the Secret Key
   2. local_dns_server (optional): Enter Local Domains and the IP for the local DNS e.g. Entra ID (aka Active Directory). See the Optional Parameters for more detail
3. Save the file
4. Under Install, download the Relay executable file (labeled DNSFilter for Windows/macOS/Linux)

Step three: Run the executable file

1. Confirm the relay.conf and executable files are in the same folder/directory
2. Run the executable file

Step four: Test the connection

Test the connection with the nslookup command in the Virtual Machine or another device on the network. 

• nslookup -type=txt debug.dnsfilter.com 127.0.0.1

• nslookup -type=txt debug.dnsfilter.com <internal IP address>

A good output that confirms the Relay is connected looks similar to this: 

Non-authoritative answer:

debug.dnsfilter.com text = “time=2022-02-23 22:02:45.528505065 +0000 UTC
debug.dnsfilter.com text = “serverid=55802”
debug.dnsfilter.com text = “serverip=103.247.36.36"
debug.dnsfilter.com text = “serverport=53”

A bad output will return similar to this:

Non-authoritative answer:
*** Can’t find debug.dnsfilter.com: No answer
Authoritative answers can be found from: dnsfilter.com
origin = amir.ns.cloudflare.com

mail addr = dns.cloudflare.com

serial = 2271027187

refresh = 10000

retry = 2400

expire = 604800

minimum = 3600

See our Relay connection troubleshooting article for steps to fix the deployment if returned a bad output.