Trusted Recursive Resolver

DNS-over-HTTPS (DoH) allows DNS to be resolved with enhanced privacy, secure transfers and comparable performance. This page describes Firefox configuration settings related to DoH in detail, and offers some explanation of internal operations of the implementation.

Mozilla operates a Trusted Recursive Resolver program, whose requirements are documented at Security/DOH-resolver-policy. All TRRs offered by Firefox conform to the requirements described in the policy, but not vice versa().

For more information, we've created documentation about DoH and our plans for deployment. We also have an FAQ, and instructions for network operators who wish to disable DoH on their networks.

DNS-over-HTTPS Settings in Firefox

All preferences for the DNS-over-HTTPS functionality in Firefox are located under the `network.trr` prefix (TRR == Trusted Recursive Resolver). The support for these were added in Firefox 62.

network.trr.mode

The resolver mode. You should not change the mode manually, instead use the UI in the Network Settings section of about:preferences

• 0 - Off (default). use standard native resolving only (don't use TRR at all)
• 1 - Reserved (used to be Race mode)
• 2 - First. Use TRR first, and only if the name resolve fails use the native resolver as a fallback.
• 3 - Only. Only use TRR, never use the native resolver.
  • Up to FF >= 73, this mode also requires the bootstrapAddress pref to be set.
  • Starting with Firefox 74, setting the bootstrap address is no longer mandatory - the browser will simply bootstrap itself using regular DNS, unless the DoH server domain can't be resolved.
  • The native resolver will still be used for portal detection and telemetry (Bug 1593873)
• 4 - Reserved (used to be Shadow mode)
• 5 - Off by choice. This is the same as 0 but marks it as done by choice and not done by default.

network.trr.uri

(default: none) set the URI for your DoH server. That's the URL Firefox will issue its HTTP request to. It must be a HTTPS URL. If "useGET" is enabled, Firefox will append "?dns=...." to the URI when it makes its HTTP requests. For the default POST requests, they will be issued to exactly the specified URI.

Publicly announced servers include:

• https://mozilla.cloudflare-dns.com/dns-query
• https://dns.google/dns-query

For more servers, see this unofficial list of DoH servers: https://github.com/curl/curl/wiki/DNS-over-HTTPS.

network.trr.resolvers

A list of potential resolvers for the user interface. When enabled, the TRR service will always use the value of "network.trr.uri".

network.trr.credentials

(default: none) set credentials that will be used in the HTTP requests to the DoH end-point. It is the right-hand side content, the value, sent in the Authorization: request header.

network.trr.wait-for-portal

(default: false) set this boolean to **true** to tell Firefox to wait for the captive portal detection before TRR is used. (on Android, this will default to **false** since the captive portal handling is done outside of Firefox, by the OS itself.)

network.trr.allow-rfc1918

(default: false) set this to true to allow RFC 1918 private addresses in TRR responses. When set to false, any such response will be considered invalid and won't be used.

network.trr.useGET

(default: false) When the browser issues a request to the DoH server to resolve host names, it can do that using POST or GET. By default Firefox will use POST, but by toggling this you can enforce GET to be used instead.

network.trr.confirmationNS

(default: example.com) Firefox will check an NS entry at startup to verify that TRR works to ensure proper configuration. This preference sets which domain to check. The verification only checks for a positive answer, it doesn't actually care what the response data says. Set this to `skip` to completely avoid confirmation.

network.trr.bootstrapAddress

(default: none) by setting this field to the IP address of the host name used in "network.trr.uri", you can bypass using the system native resolver for it. Use this to get the IPs of the cloudflare server: https://dns.google/query?name=mozilla.cloudflare-dns.com

Starting with Firefox 74 setting the bootstrap address is no longer required in mode 3. Firefox will attempt to use regular DNS in order to get the IP address of the trusted resolver. However, if DNS resolution of the resolver domain fails, setting the bootstrap address is again necessary.

network.trr.blacklist-duration

(default: 60) is the number of seconds a name will be kept in the TRR blacklist until it expires and then will be tried with TRR again. The default duration is one minute.

Entries are added to the TRR blacklist when the resolution fails with TRR but works with the native resolver, or if the subsequent connection with a TRR resolved host name fails but works with a retry that is resolved natively. When a hostname is added to the TRR, its domain gets checked in the background to see if the whole domain should be blacklisted to ensure a smoother ride going forward.

network.trr.request_timeout_ms

(default: 1500) is the number of milliseconds a request and the corresponding response from the DoH server is allowed to take until considered failed and discarded.

network.trr.request_timeout_mode_trronly_ms

(default: 30000) is the number of milliseconds a request and the corresponding response from the DoH server is allowed to take until considered failed and discarded in TRR-only mode.

network.trr.early-AAAA

(default: false) For each normal name resolution, Firefox issues one HTTP request for A entries and another for AAAA entries. The responses come back separately and can come in any order. If the A records arrive first, Firefox will—as an optimization— continue and use them without waiting for the second response. If the AAAA records arrive first, Firefox will only continue and use them immediately if this option is set to **true**.

network.trr.skip-AAAA-when-not-supported

(default: true) If Firefox detects that your system does not have IPv6 connectivity, it will not request IPv6 addresses from the DoH server.

network.trr.wait-for-A-and-AAAA

(default: true) When true, the DNS request will wait for both A and AAAA responses (if both have been requested) before notifying the listeners. When true, it effectively cancels `network.trr.early-AAAA`

network.trr.max-fails

(default: 5) If this many DoH requests fail in a row, consider TRR broken and go back to verify-NS state. This is meant to detect situations when the DoH server dies.

network.trr.disable-ECS

(default: true) If set, TRR asks the resolver to disable ECS (EDNS Client Subnet: the method where the resolver passes on the subnet of the client asking the question). Some resolvers will use ECS to the upstream if this request is not passed on to them.

network.trr.excluded-domains

(default: ``) Comma separated list of domain names to be resolved using the native resolver instead of TRR. Users may add domains they wish to exclude from TRR to this pref.

This pref can be used to make /etc/hosts works with DNS over HTTPS in Firefox. Setting network.trr.excluded-domains to include host names from /etc/hosts will make them fall back to platform DNS, which will use the rules in /etc/hosts.

network.trr.builtin-excluded-domains

(default: `localhost,local`) Comma separated list of domain names to be resolved using the native resolver instead of TRR. The host of the captive portal detection is also added to the exclusion list internally, in order to be able to detect local captive portals. Users should change this pref as it may get overwritten by changes to the default values.

network.trr.enable_when_vpn_detected

(default: false) When false if a Windows VPN is detected on the system then TRR will be disabled. If true, VPN status will be ignored when deciding if to enable TRR.

network.trr.enable_when_proxy_detected

(default: false) When false if a Windows Proxy is detected on the system then TRR will be disabled. If true, VPN status will be ignored when deciding if to enable TRR.

network.trr.enable_when_nrpt_detected

(default: false) When false on Windows if NRPT is detected on the system then TRR will be disabled. If true, VPN status will be ignored when deciding if to enable TRR.

network.trr.send_user-agent_headers

(default: false) When false the User-Agent header will not be set on TRR requests.

network.trr.send_accept-language_headers

(default: false) When false the Accept-Language header will not be set on TRR requests.

network.trr.clear-cache-on-pref-change

(default: true) When true, the DNS+TRR cache will be cleared when a relevant TRR pref changes. (uri, bootstrapAddress, excluded-domains)

Dynamic Blacklist

To keep the failure rate at a minimum, the TRR system manages a dynamic persistent blacklist for host names that can't be resolved with DOH but works with the native resolver. Blacklisted entries will not be retried over DOH for a couple of days. "localhost" and names in the ".local" TLD will never be resolved via DOH.

When TRR starts up, it will first verify that it works by first checking a "confirmation" domain name. This confirmation domain is a pref by default set to "example.com".

Notes

DNS

TRR bypasses system DNS so you might not be using any 'enhanced' DNS services provided by your default DNS server which may include Web Content Filtering or basic Malware Protection, phishing protection.

ESNI

The way ESNI is currently implemented requires TRR. When TRR is disabled ESNI will not work because the platform DNS APIs don't allow retrieving TXT records.

See also

• Initial ticket: https://bugzilla.mozilla.org/show_bug.cgi?id=1434852
• The DNS-over-HTTPS spec: https://tools.ietf.org/html/rfc8484

• https://support.mozilla.org/en-US/kb/configuring-networks-disable-dns-over-https