DNS Relay Deployment Guide

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 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 18.04 64bit - With auto-updating, it uses our docker container. (Recommended)

Relay Images

Use the links below for guidance within these particular environments.

• Relay VirtualBox Image 

• Relay VMware Image 

• Relay Hyper-V Image 

• Relay Azure Cloud Image

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'

    services:
      relay:
        image: dnsfilter/relay:latest
        network_mode: host
        logging:
          driver: "json-file"
          options:
            max-size: 100m
        volumes:
          - "./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

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).

  api_url="https://api.dev.dnsfilter.sh
  # Proxy listening address, optional, defaults to :53
  #listen_addresses = [ "127.0.0.1:28000" ]
  # 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" ]
  
  [log]
  # Console error log, defaults to "error"
  # Set to "debug" for troubleshooting
  level = "error"
  
  [client]
  name = "Your Network"
  secret_key = "somesecretkey"
  
  # Local DNS servers to forward domain specific requests
  [[local_dns_server]]
  #addresses = [ "10.0.0.1:53", "10.0.0.2:53" ]
  #local_domains = [ "local.domain", "my.lan" ]
  
  # The sections below are for testing purposes only
  # ------------------------------------------------
  # "Normal" Upstream servers, defaults to DNSFilter DNS Servers 103.247.36.36 and 103.247.37.37
  #[[upstream_server]]
  #ip_address = "45.77.74.115"
  # Optional, defaults to 53
  #port = 53
  
  # "TLS" Upstream servers, defaults to DNSFilter DNS-over-TLS Servers 103.247.36.36 and 103.247.37.37
  #[[tls_upstream_server]]
  #auth_name = "dev-dns2.dnsfilter.com"
  #ip_address = "45.77.74.115"
  # Optional, defaults to 853
  #port = 853
  # Optional, useful for self-signed certs
  #[[tls_upstream_server.pinhash]]
  #digest = "sha256"
  #hash = "lrdOgE4H0RyJiSVe9360dSqUu8w0iA8O1cjAsUMijAY="
  #[[tls_upstream_server.pinhash]]
  #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

   
           network:
               version: 2
               renderer: networkd
               ethernets:
               ens3:
                   dhcp4: no
                   addresses:
                   - 192.168.1.16/24
                   gateway4: 192.168.1.1
                   nameservers:
                       addresses: [8.8.8.8, 1.1.1.1]

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

Version Log

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