DNSFilter Knowledge Base

DNSFilter Relay Overview

The DNSFilter Relay allows your organization to have greater visibility of DNS traffic on your network. Under a normal site deployment, you are able to see Queries coming from a location as an aggregate whole, but unable to see which machine on your network these queries originated from.

Using the Relay, requests are sent from client devices directly to the proxy, which performs split-horizon DNS resolution. The proxy will look into its configuration to see if the request matches a domain that is designated as local. If so, it will handoff the request to the DNS server on the LAN. Otherwise, it will tag the request with information that identifies the client (hostname, address, etc) and send it to DNSFilter to be processed according to your policy.

For local domain documentation, please click here!

By tagging DNS requests destined for DNSFilter, this allows:

  1. Additional logging and reporting at the LAN IP / subnet level
  2. Policy enforcement based on LAN IP or LAN subnet

Finally, Relay supports sending DNS requests:

  1. Via UDP (port 53 or 5353)
  2. Via TCP (port 53 or 5353)
  3. Via DNS over TLS (DoT) Encryption (port 853 or port 443)

Relay is available in a few forms:
It is recommended you choose VM (it auto-updates) or the docker container, which can be easily updated.

  1. Virtual Machine - Ubuntu 18.04 64bit - With auto-updating, uses our docker container.
  2. Docker Container - All above architectures, via docker hub.
  3. Binary - Linux 64-bit, Windows 64-bit, arm, arm64, mipsle, MacOS 64-bit


Download a sample config file (same as shown below)
You will need to create a Deployment site in our UI and then find the associated sitekey
Local Domains and the IP for your local DNS (ex: Active Directory) can optionally be configured. The config file can be found at /etc/relay/relay.conf if you choose an installation method where manual manipulation of the config is required.

Note: 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 else it will automatically become part of the last TOML Table).

# Proxy listening address, optional, defaults to :53
#listen_addresses = [ "" ]
# SO reuse port true/false, defaults to false
so_reuse_port = true

# Desired upstream use order, defaults to "udp", "tcp", "tcp-tls", set only one to disable the others
upstream_order = [ "udp", "tcp", "tcp-tls" ]

# Console error log, defaults to "error"
# Set to "debug" for troubleshooting
level = "error"

name = "Your Network"
secret_key = "somesecretkey"

# Local DNS servers to forward domain specific requests
#addresses = [ "", "" ]
#local_domains = [ "local.domain", "my.lan" ]

# The sections below are for testing purposes only
# ------------------------------------------------
# "Normal" Upstream servers, defaults to DNSFilter DNS Servers and
#ip_address = ""
# Optional, defaults to 53
#port = 53

# "TLS" Upstream servers, defaults to DNSFilter DNS-over-TLS Servers and
#auth_name = "dev-dns2.dnsfilter.com"
#ip_address = ""
# Optional, defaults to 853
#port = 853
# Optional, useful for self-signed certs
#digest = "sha256"
#hash = "lrdOgE4H0RyJiSVe9360dSqUu8w0iA8O1cjAsUMijAY="
#digest = "sha256"
#hash = "this is an invalid hash"




Download Link



















Docker Container

Container is located in Docker Hub
You can also reference the following ansible script to automate setup.
We recommend installing ansible, and executing this script via cron hourly, to auto-update your containers upon new releases.

docker run --network="host" -v /etc/relay:/etc/relay dnsfilter/relay /go/bin/relay-linux-amd64 -c /etc/relay/relay.conf -r /etc/relay

Virtual Machine

Recommended specs: 64-bit 2 core CPU; 2GB of ram.
Recommended configuration is two separate Relay VM instances - listening on different LAN IPs; so you can hand these two DNS IPs out via DHCP.

VirtualBox Ubuntu 18.04 (2GB)

user: dnsfilter
pass: ChangeMeNow!


Root Permissions

These commands require root privileges. You can either prepend sudo to each command or login as the root user with sudo su.

Change the VM to use a bridged network interface instead of NAT
Modify the /etc/relay/relay.conf config by entering your sitekey.
systemctl enable docker.service
systemctl start docker.service
By default the VM runs two docker instances of relay which load balance traffic requests.
Every hour a system cron job checks for a new docker container, and if it exists, updates one, followed by the other. This upgrade should be without interruption.

ESXi VMWare Image

If you're going to use ESXi to run this VirtualBox Image - we have made a ESXi image to help. Download the ESXi image here. We followed this guide to make the image.

  1. If you experience a checksum(s) error you will need to generate a new checksum.

On macOS you can accomplish this through the command line. Run the following commands and update relay.mf (the manifest file) with the output.

shasum /path/to/relay-disk1.vmdk
shasum /path/to/relay.ovf

On Windows you can download the Microsoft File Checksum Integrity Verifier and generate a new checksum for relay-disk1.vmdk and relay.ovf. Update the manifest file relay.mf with the new values.

There's a great blog post on using Microsoft's Checksum tool. Search for "Now that we made all the change, we are ready to generate a new Sha key"

  1. You will likely need to alter the ethernet network adapter within the Virtual Machine to match your server.

Edit the file /etc/netplan/50-cloud-init.yaml and change enp0s3 to the correct interface name which would need to be discovered on the host. After the change run: netplan apply to enable the change.


Root Permissions

These commands require root privileges. You can either prepend sudo to each command or login as the root user with sudo su.

Setting a Static IP in Ubuntu

Your deployment will likely need a static IP address set on the Relay server. Ubuntu uses netplan for network settings. More information can be found on Canonical's netplan website. Here are the steps for Ubuntu. First edit the cloud init file.

nano /etc/netplan/50-cloud-init.yaml

Here's an example of how you should edit the file. Change the ethernets addresses to the desired static IP and change enp0s3 to the correct interface name which would need to be discovered on the host.

  version: 2
  renderer: networkd
      dhcp4: no
          addresses: [,]

After the change run: sudo netplan apply to enable the change.



After applying the new static IP settings the VM will immediately change to the new IP. If you've logged in via ssh the session will be immediately terminated if the static IP is different from the DHCP IP.


For troubleshooting purposes, you may enable debug logging in the configuration file. This enabled you to see the local query logs.

Coming Relay Features

  • LAN Device Reports (currently LAN device IP is only available in CSV)
  • LAN IP enumeration and hostname labeling tool

Version Log

You can find the history of the Relay release notes on our public changelog.

Updated 7 months ago


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.