Enabling DNS-over-TLS

Article author
Josh L
  • Updated

DNSFilter supports DNS-over-TLS, allowing for encryption and privacy of DNS traffic (for more details on DNS encryption techniques, check out this article).

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/DNS\ Agent/daemon.conf
    1. Set the upstream_order as shown in the snippet below at the top of the config file.

# 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

With version 1.0.8 DoT is now enabled by default on the iOS roaming client, no longer requiring the end-user to configure manually. However, for any older versions, or to change this option;

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


This would disable DoT on all devices that use this dnsfilter.mobileconfig file. 

Alternatively, if you would only like to edit one device, this can be disabled within the iOS RC Settings as shown below: 


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 be helpful.

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: "."

Implementation Details

Feature Supported
TLS Versions 1.3
RFC-7828 Yes
TCP_FastOpen Yes
TCP_FalseStart Yes

Was this article helpful?

4 out of 7 found this helpful

Have more questions? Submit a request



Article is closed for comments.