Cloudflare Docs
Learning Paths
Edit this page
Give us feedback
Set theme to dark (⇧+D)

Resolve private DNS

  4 min read

By default, all DNS requests on the user device are resolved by Cloudflare’s public DNS resolver except for common top level domains used for local resolution (such as localhost). To allow users to connect to internal server names or domains that do not resolve on the public Internet, you have two options:

​​ Local Domain Fallback

Local Domain Fallback tells the WARP client to send specific DNS requests to your private DNS resolver instead of to Cloudflare’s public DNS resolver. This method was the primary delivery mechanism for private DNS for a long time, and is the simplest option, but it has two shortcomings: you cannot deterministically route private DNS queries to different resolvers based on specific attributes, and you cannot apply Gateway DNS policies to this traffic because Cloudflare is not resolving it.

To learn more about how Local Domain Fallback works, refer to How the WARP client handles DNS requests.

​​ Add a domain

To add a domain to the Local Domain Fallback list:

  1. In Zero Trust, go to Settings > WARP Client.

  2. Under Device settings, locate the device profile you would like to view or modify and select Configure.

  3. Scroll down to Local Domain Fallback and select Manage.

  1. In Domain, enter the apex domain (example.com) that you want to resolve using your private DNS server. All prefixes under the apex domain are subject to local domain fallback (in other words, example.com is interpreted as *.example.com).

  2. In DNS Servers, enter the IP address of the DNS server that should resolve that domain name.

    • WARP tries all servers and always uses the fastest response, even if that response is no records found.
    • We recommend specifying at least one DNS server for each domain. If a value is not specified, the WARP client will try to identify the DNS server (or servers) used on the device before it started, and use that server for each domain in the Local Domain Fallback list.
  3. Enter an optional description and select Save domain.

  4. Ensure that the WARP client can proxy DNS traffic to your private DNS server:

    1. Go to Networks > Routes and verify that the DNS server is connected via Cloudflare Tunnel (either cloudflared or WARP Connector).
    2. In your Split Tunnel configuration, verify that the DNS server IP routes through the WARP tunnel.

​​ Resolver policies

Custom resolver policies provide similar functionality to Local Domain Fallback but occur in Cloudflare Gateway rather than on the local device. This option is recommended if you want more granular control over private DNS resolution. For example, you can ensure that all users in a specific geography use the private DNS server closest to them, ensure that specific conditions are met before resolving private DNS traffic, and apply Gateway DNS policies to private DNS traffic.

​​ Create a resolver policy

  1. In Zero Trust, go to Gateway > Resolver policies.

  2. Select Add a policy.

  3. Create an expression for your desired traffic. For example, you can resolve a hostname for an internal service:

    SelectorOperatorValue
    Hostininternal.example.com
  4. In Select DNS resolver, choose Configure custom DNS resolvers.

  5. Enter the IP addresses of your custom DNS resolver.

  6. In Network, choose whether to route queries publicly (to the Internet) or privately (to a private network service).

  7. (Optional) Enter a custom port for each IP address.

  8. Select Create policy.

Custom resolvers are saved to your account for future use. You can add up to 10 IPv4 and 10 IPv6 addresses to a policy.

When a user’s query matches a resolver policy, Gateway will send the query to your listed resolvers in the following order:

  1. Public resolvers
  2. Private resolvers behind the default virtual network for your account
  3. Private resolvers behind a custom virtual network

Gateway will cache the fastest resolver for use in subsequent queries. Resolver priority is cached on a per user basis for each data center.