DNSFilter Knowledge Base


DNSFilter supports DNS-over-TLS, allowing for encryption and privacy of DNS traffic.


DNS-over-TLS hostnames

The hostnames for DNSFilter are listed below:

  • dns1.dnsfilter.com
  • dns2.dnsfilter.com

Roaming Client Support

DNS-over-TLS is supported in our desktop roaming clients, as well as in the DNS Relay. Instructions for enabling DNS-over-TLS are provided below:

Windows Roaming Client

After installing the Windows roaming client, you may create the following registry key value to set "tcp-tls" as the preferred connection method.

For the retail version of the roaming client:

reg add "HKLM\Software\DNSFilter\Agent" /v UpstreamOrder /d "tcp-tls,udp,tcp" /f

For the MSP/whitelabel edition of the roaming client:

reg add "HKLM\Software\DNSAgent\Agent" /v UpstreamOrder /d "tcp-tls,udp,tcp" /f

MacOS Roaming Client

  1. Open the daemon.conf file for editing.

For the retail version:

sudo nano /Library/Application\ Support/DNSFilter\ Agent/daemon.conf

For the MSP/whitelabel edition:

sudo nano /Library/Application\ Support/DNSFilter\ Agent/daemon.conf
  1. Set the upstream_order as shown in the snippet below:
# Desired upstream use order, defaults to "udp", "tcp", "tcp-tls", set only one to disable the others
upstream_order = [ "tcp-tls", "udp", "tcp" ]

iOS Roaming Client

  1. Open the dnsfilter.mobileconfig file
  2. Set the dns_over_tls_enabled key as shown in the snippet below within the <dict> section:

DNS Relay

Add the upstream_order value to the top of the relay.conf file as shown below:

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

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

Forwarder/Stub Support

A typical setup for DNS-over-TLS is to configure a LAN DNS Server to act as a forwarder, wrapping LAN queries into secure packets.

Below are several example software configurations:

Knot Resolver

Specific instructions for Knot Resolver will depend on the local configuration and operating system. Please see Knot Resolver's documentation regarding TLS forwarding for more. This blog post might also come in handy.

To implement TLS forwarding, in the policy modules section, we use policy.TLS_FORWARD:

The target of ca_file= may not be needed or may differ.

modules = { 'policy' }
{'', hostname='dns1.dnsfilter.com', ca_file='/etc/knot-resolver/tlsca.crt'}
{'', hostname='dns2.dnsfilter.com', ca_file='/etc/knot-resolver/tlsca.crt'} })
} #This signifies the end of the { 'policy' } section

Stubby + Unbound

A dual-Docker solution, where Unbound is used as a DNS-caching forwarder, and Stubby is used as a DNS-over-TLS transport server between Unbound and DNSFilter. This combines the caching powers of Unbound with the high-performing DNS-over-TLS implantation that Stubby provides.

Link to the GitHub Project.

Stubby (Standalone)

In the upstream_recursive_servers: section of stubby.yaml:

- address_data:
tls_auth_name: "dns1.dnsfilter.com"
- address_data:
tls_auth_name: "dns2.dnsfilter.com"

Unbound (Standalone)

The default DNS forwarder in the open-source firewalls IPFire and pfSense.



DNS-over-TLS performance in Unbound is relatively poor. About 8-10 queries per second is our suggested maximum, so only low-traffic networks are suggested. Consider using Knot Resolver or the Stubby + Unbound Docker solution.

In the unbound.conf file, ensure the following is set in the server: section. DNSFilter must be the only two forwarder addresses configured.

ssl-upstream: yes
name: "."
forward-addr: [email protected]
forward-addr: [email protected]

Implementation Details




TLS Versions


TLS 1.3 will be supported when OpenSSL 1.1.1 is released



AKA: (edns-tcp-keepalive)



Awaiting Golang 1.11



Awaiting Golang 1.11

Updated 6 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.