DNS policies

DNS policies let you control which websites and services your users can reach by inspecting their DNS queries — the lookups that translate domain names into IP addresses. Because DNS policies act at the lookup stage, they work across all protocols and applications, not just web browsers.

When a user makes a DNS request, Gateway matches the request against the DNS policies you have set up for your organization. If the domain does not belong to any blocked categories, or if it matches an Allow or Override policy, the user's client receives an address based on DNS resolution from Cloudflare's public DNS resolver (1.1.1.1). You can also use a resolver policy to redirect DNS requests to a custom server.

A DNS policy consists of an Action as well as a logical expression that determines the scope of the action. To build an expression, you need to choose a Selector and an Operator, and enter a value or range of values in the Value field. You can use And and Or logical operators to evaluate multiple conditions.

• Actions
• Selectors
• Comparison operators
• Value
• Logical operators

When creating a DNS policy, you can select as many security risk categories and content categories as needed to fully secure your network. Unless a more specific selector is configured in a policy (for example, User Email or Source IP), then the policy will be evaluated against all DNS queries that reach Gateway from your organization.

If a condition in an expression joins a query attribute (such as Source IP) and a response attribute (such as Resolved IP), then the condition will be evaluated when the response is received.

The action determines what Gateway does when a DNS query matches your policy conditions. You can assign one action per policy.

These are the action types you can choose from:

• Allow
• Block
• Override
• Safe Search
• YouTube Restricted Mode

API value: allow

Policies with Allow actions explicitly permit DNS queries to resolve. Gateway uses a first-match principle, which means that if an Allow policy matches a query at a higher precedence than a Block policy, the query will be allowed to resolve. For example, the following configuration allows DNS queries to reach domains categorized as belonging to the Education content category:

DNSSEC (Domain Name System Security Extensions) verifies that DNS responses have not been tampered with by checking a cryptographic signature attached to the record. When you select Disable DNSSEC validation, Gateway will resolve DNS queries even if the signature cannot be validated. We do not recommend disabling DNSSEC validation unless you know that the validation failure is due to DNSSEC configuration issues and not malicious attacks.

API value: block

Policies with Block actions prevent DNS queries from resolving for destinations you specify within the Selector and Value fields. For example, the following configuration blocks DNS queries from reaching domains categorized as belonging to the Adult Themes content category:

When choosing the Block action, turn on Modify Gateway block behavior to respond to queries with a block page to display to users who go to blocked websites. Optionally, you can override your global block page setting with a URL redirect for the specific DNS policy. For more information, refer to Block page.

If the block page is turned off for a policy, Gateway will respond to blocked queries with an A record (IPv4) of 0.0.0.0 or an AAAA record (IPv6) of ::. Because no server responds at these addresses, the browser will display its default connection error page.

To block the resolution of queries for DNS records with types other than A or AAAA, Gateway will respond with the REFUSED (RCODE:5) DNS return code. Gateway will block the request but will not display a block page.

Turn on Display block notification for Cloudflare One Client to display notifications for Gateway block events. Blocked users will receive an operating system notification from the Cloudflare One Client with a custom message you set. If you do not set a custom message, the Cloudflare One Client will display a default message. Custom messages must be 100 characters or less. The Cloudflare One Client will only display one notification per minute.

Upon selecting the notification, the Cloudflare One Client will direct your users to the Gateway block page you have configured. Optionally, you can direct users to a custom URL, such as an internal support form.

When you turn on Send policy context, Gateway will append details of the matching request to the redirected URL as a query string. Not every context field will be included. Potential policy context fields include:

Ensure that your operating system allows notifications for the Cloudflare One Client. Your device may not display notifications if focus, do not disturb, or screen sharing settings are turned on. To turn on client notifications on macOS devices running DisplayLink software, you may have to allow system notifications when mirroring your display. For more information, refer to the macOS documentation ↗.

API value: override

Policies with Override actions replace the real DNS answer with a destination you specify. When a user queries a domain that matches the policy, Gateway returns your custom IP address or hostname instead of the actual DNS record. For example, you can provide a custom response IP of 1.2.3.4 for all queries to www.example.com with the following policy:

API value: safesearch

SafeSearch is a feature of search engines that helps you filter explicit or offensive content. When you enable SafeSearch, the search engine filters explicit or offensive content and returns search results that are safe for children or at work.

You can use Cloudflare Gateway to enable SafeSearch on search engines like Google, Bing, Yandex, YouTube and DuckDuckGo. For example, to enable SafeSearch for Google, you can create the following policy:

API value: ytrestricted

Similarly, you can enforce YouTube Restricted mode by choosing the YouTube Restricted action. YouTube Restricted Mode is an automated filter for adult and offensive content built into YouTube. To enable YouTube Restricted Mode, you could set up a policy like the following:

This setup ensures users will be blocked from accessing offensive sites using DNS.

Gateway matches DNS queries against the following selectors, or criteria.

Each selector is evaluated during a specific phase of the DNS resolution process:

• Before DNS resolution — Gateway inspects properties of the incoming query (for example, the domain name or source IP) before looking up the answer.
• During DNS resolution — Gateway inspects information discovered while resolving the query (for example, the authoritative nameserver IP).
• After DNS resolution — Gateway inspects the DNS answer (for example, the resolved IP or CNAME record) after resolution completes.

The Override action cannot be used with selectors evaluated during or after DNS resolution, because the override must be applied before the answer is returned. For more information on how evaluation phase interacts with precedence, refer to order of enforcement.

You can apply DNS policies to a growing list of popular web applications. Refer to Application and app types for more information.

Use this selector to match against the IP address of the authoritative nameserver IP address.

Use this selector to filter domains belonging to specific content categories.

When using an Allow or Block action, you can optionally block IP addresses or filter categories for CNAME records.

Use this selector to filter DNS responses by their CNAME records.

Use this selector to filter DNS responses by their MX records.

Use this selector to filter DNS responses by their PTR records.

Use this selector to apply policies to DNS queries that arrived to your Gateway Resolver IP address aligned with a registered DNS location. For most Gateway customers, this is an IPv4 anycast address and policies created using this IPv4 address will apply to all DNS locations. However, each DNS location has a dedicated IPv6 address and some Gateway customers have been supplied with a dedicated IPv4 address — these both can be used to apply policies to specific registered DNS locations.

Use this selector to filter DNS responses by their TXT records.

Use this selector to match against DNS queries that arrive via DNS-over-HTTPS (DoH) destined for the DoH endpoint configured for each DNS location. For example, you can use a DNS location with a DoH endpoint of abcdefg.cloudflare-gateway.com by choosing the DoH Subdomain selector and inputting a value of abcdefg.

Use this selector to match against a domain and all subdomains. For example, you can match example.com and its subdomains, such as www.example.com.

Gateway policies do not support domains with non-Latin characters directly. To use a domain with non-Latin characters, add it to a list.

Use this selector to match against only the hostname specified. For example, you can match test.example.com but not example.com or www.test.example.com.

Gateway policies do not support hostnames with non-Latin characters directly. To use a hostname with non-Latin characters, add it to a list.

Use this selector to match against custom indicator feeds.

You can use a publicly available indicator feed or a custom indicator feed assigned to your account by a designated third-party vendor. For more information on indicator feeds, refer to Custom Indicator Feeds.

When using an Allow or Block action, you can optionally block IP addresses or filter categories for CNAME records.

Use this selector to apply policies to a specific Gateway DNS location or set of locations.

Use this selector to choose the DNS resource record type that you would like to apply policies against. For example, you can match A records for a domain but not MX records.

Use this selector to filter based on the continent that the query resolves to. Geolocation is determined from the IP address in the response. To specify a continent, enter its two-letter code into the Value field:

• AF - Africa
• AN - Antarctica
• AS - Asia
• EU - Europe
• NA - North America
• OC - Oceania
• SA - South America

Use this selector to filter based on the country that the query resolves to. Geolocation is determined from the IP address in the response. To specify a country, enter its ISO 3166-1 Alpha 2 code ↗ in the Value field.

Use this selector to filter based on the IP addresses that the query resolves to.

Use this selector to match a dynamic list of category IDs sent in the EDNS (Extension Mechanisms for DNS) ↗ portion of a DNS query. EDNS allows extra metadata to be attached to a DNS query beyond the standard fields. Gateway reads category IDs from the EDNS OPT code 65050.

Use this selector to match domains (and optionally, IP addresses) belonging to specific security categories.

When using an Allow or Block action, you can optionally block IP addresses or filter categories for CNAME records.

Use this selector to filter based on the continent where the query arrived to Gateway from.

Geolocation is determined from the device's public IP address (typically assigned by the user's ISP). To specify a continent, enter its two-letter code into the Value field:

Use this selector to filter based on the country where the query arrived to Gateway from.

Geolocation is determined from the device's public IP address (typically assigned by the user's ISP). To specify a country, enter its ISO 3166-1 Alpha-2 code ↗ in the Value field.

Use this selector to apply policies to the source IP address of DNS queries. For example, this could be the WAN IP address of the stub resolver used by your organization to send queries to Gateway.

Use this selector to apply policies to the source internal IP address of a DNS query. For example, this could be the private IP address of the hosts behind Cloudflare WAN (formerly Magic WAN) or Cloudflare Mesh used by your organization to send queries to Gateway.

Use these selectors to match against identity attributes.

Comparison operators are the way Gateway matches traffic to a selector. When you choose a Selector in the dashboard policy builder, the Operator dropdown menu will display the available options for that selector.

In the Value field, you can input a single value when using an equality comparison operator (such as is) or multiple values when using a containment comparison operator (such as in). Additionally, you can use regular expressions (or regex) to specify a range of values for supported selectors.

Regular expressions are evaluated using Rust. The Rust implementation is slightly different than regex libraries used elsewhere. For more information, refer to our guide for Wildcards. To evaluate if your regex matches, you can use Rustexp ↗.

If you want to match multiple values, you can use the pipe symbol (|) as an OR operator. You do not need to use an escape character (\) before the pipe symbol. For example, the following expression evaluates to true when the hostname matches either .*whispersystems.org or .*signal.org:

In addition to regular expressions, you can use logical operators to match multiple values.

To evaluate multiple conditions in an expression, select the And logical operator. These expressions can be compared further with the Or logical operator.

The Or operator will only work with conditions in the same expression group. For example, you cannot compare conditions in Traffic with conditions in Identity.

Gateway will not properly filter traffic sent through third-party VPNs or other Internet filtering software, such as iCloud Private Relay ↗ or Google Chrome IP Protection ↗. To ensure your DNS policies apply to your traffic, Cloudflare recommends turning off software that may interfere with Gateway.

To turn off iCloud Private Relay, refer to the Apple user guides for macOS ↗ or iOS ↗.

To apply DNS policies to queries forwarded through Cloudflare WAN, you can either point your organization's DNS resolver to an IPv6, DNS over HTTPS (DoH), or DNS over TLS (DoT) endpoint or request a dedicated resolver IPv4 address. For more information, refer to DNS resolver IPs and hostnames.

Some applications (for example, WhatsApp and Android Studio) have backup DNS servers built into their code. If their primary DNS query is blocked by Gateway, these apps automatically retry the query against their built-in DNS servers (for example, Google's 8.8.8.8), which bypasses your policies entirely. To mitigate this behavior, you create a Gateway Network policy to block outbound DNS traffic on TCP/UDP port 53 to the fallback DNS servers. For example, to block Google's fallback DNS servers: