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.
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, uses our docker container.
- Docker Container - All below architectures, via docker hub
- 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 = [ "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 188.8.131.52 and 184.108.40.206 #[[upstream_server]] #ip_address = "220.127.116.11" # Optional, defaults to 53 #port = 53 # "TLS" Upstream servers, defaults to DNSFilter DNS-over-TLS Servers 18.104.22.168 and 22.214.171.124 #[[tls_upstream_server]] #auth_name = "dev-dns2.dnsfilter.com" #ip_address = "126.96.36.199" # 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"
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.
Notes on common errors with Relay binaries and Docker containers:
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).
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 188.8.131.52 or 184.108.40.206 to your system as per the instructions for your distribution, and this issue should resolve.
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.
Relay VirtualBox Image
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.
Click here to download the VirtualBox Ubuntu 18.04 file (2GbB
In order to user the VirtualBox image:
- Change the VM to use a bridged network interface instead of NAT
- Modify the
/etc/relay/relay.confconfig by entering your sitekey.
sudo systemctl enable docker.service
sudo 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.
Relay ESXi VMWare Image
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:
- First edit the cloud init file.
network: version: 2 renderer: networkd ethernets: ens3: dhcp4: no addresses: - 192.168.1.16/24 gateway4: 192.168.1.1 nameservers: addresses: [220.127.116.11, 18.104.22.168]
- 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.
- After the change run:
netplan applyto enable the change.
You can find the history of the Relay release notes on our public changelog.