DNS Relay Deployment Guide

Article author
Chris Todd
  • Updated


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 hand the request to the DNS server on the LAN. Otherwise, it will tag the request with information that identifies the client (ipv4 address) and send it to DNSFilter to be processed according to your policy.


By tagging DNS requests destined for DNSFilter, this allows:

  • Additional logging and reporting at the LAN IP/Subnet level
  • Policy enforcement based on LAN IP or LAN subnet

Finally, Relay supports sending DNS requests:

  • Via UDP (port 53 or 5353)
  • Via TCP (port 53 or 5353)
  • 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.

Virtual Machine

Ubuntu 22.04 LTS - With auto-updating, it uses our docker container. (Recommended)

Relay Images

Use the links below for guidance within these particular environments.

Instructional Information Image Download
Azure Cloud Azure Cloud 22.04, 2.07 GB (zip)
Hyper-V Hyper-V 22.04, 9.9 GB (vhdx)
VirtualBox Virtual Box 22.04, 4.47 GB (ova)
VMware ESXi VMware 22.04, 3.7 MB (ova)

Relay Docker Container

The DNSFilter Relay 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

If you would prefer to use docker-compose this YAML should get you up and running in short order:

    version: '3'

        image: dnsfilter/relay:latest
        network_mode: host
          driver: "json-file"
            max-size: 100m
          - "./relay.conf:/go/bin/relay.conf"
        restart: unless-stopped

This compose file assumes that you will have a relay configuration file called relay.conf in the same directory as your docker-compose.yml file.

All below architectures:

Relay Binaries

OS Architecture Download Link
Linux 64-bit relay-linux-amd64
Windows 64-bit relay-windows-amd64.exe
linux arm relay-linux-arm
linux arm64 relay-linux-arm64
linux mipsle relay-linux-mipsle
MacOS 64-bit relay-darwin-amd64

Sample Config File

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"

Setting up 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:

  1. First, edit the cloud-init file. nano /etc/netplan/50-cloud-init.yaml
                version: 2
                renderer: networkd
                    dhcp4: no
                        addresses: [,]
  2. Change the addresses to the desired static IP and change enp0s3 to the correct interface name which would need to be discovered on the host.
  3. After the change run: netplan apply to enable the change.

Common Errors

Notes on common errors with Relay binaries and Docker containers:

Error Starting userland proxy: listen tcp4 x.x.x.x:53 bind: address already in use
By default, most modern Linux distributions will be running a DNS daemon out of the box, and that may prevent the relay from starting, as it will be unable to bind to port 53 due to the existing daemon already being bound.

You will need to disable the running DNS daemon on your host machine (or, alternatively, adjust your relay.conf file to have the container or binary listen on an entirely different port).

Post https://api.dnsfilter[...] lookup api.dnsfilter.com: Try Again

If you had to disable a DNS daemon as above, and now receive this error, there is a chance that the host machine does not have an external DNS server set, and cannot resolve the api.dnsfilter.com hostname.

Add an external DNS server such as or to your system as per the instructions for your distribution, and this issue should resolve.

not a valid TOML config file / open /go/bin/lan-proxy.conf: no such file or directory

This is a strong indication that the file expected to be found at ./relay.conf (where ./ is the same directory of your docker-compose.yml file) is either not there, named incorrectly, or unable to be accessed due to permission issues.

Ensure that relay.conf exists in the current working directory and is accessible by the Docker Daemon.

Version Log

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

Was this article helpful?

3 out of 19 found this helpful

Have more questions? Submit a request



Article is closed for comments.