DNS configuration
DNS settings choose resolvers and determine whether applications receive real or Fake IP addresses. This fragment uses DoH; replace the resolvers with services reachable from your network.
dns:
enable: true
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
default-nameserver:
- 1.1.1.1
nameserver:
- https://cloudflare-dns.com/dns-query
proxy-server-nameserver:
- https://cloudflare-dns.com/dns-query
fake-ip-filter:
- '+.lan'
- '+.local'Resolver roles
| Field | What it resolves | When to use it |
|---|---|---|
default-nameserver | DNS service hostnames | IP-based bootstrap resolver for named DoH/DoT endpoints |
nameserver | Ordinary destinations | Default resolver list |
nameserver-policy | Matching domains | Separate DNS for intranet domains or specific sites |
proxy-server-nameserver | Proxy server hostnames | Prevent DNS/proxy dependency loops, especially with rule-following DNS |
proxy-server-nameserver-policy | Specific proxy hostnames | Requires nonempty proxy-server-nameserver |
direct-nameserver | Direct outbound destinations | Separate resolvers for direct connections |
direct-nameserver-follow-policy | Policy use for direct resolution | Only relevant with direct-nameserver |
fallback / fallback-filter | Conditional alternative answers | Select by domain or primary answer; this is more than retrying after a timeout |
Resolver formats include 1.1.1.1 (UDP), tcp://1.1.1.1, tls://1.1.1.1 (DoT), and https://cloudflare-dns.com/dns-query (DoH). Include nonstandard ports in the address. system uses system DNS; see Apple behavior below.
Domain policies, hosts, and resolution modes
hosts:
printer.home.arpa: 192.168.1.20
dns:
use-hosts: true
nameserver-policy:
'+.home.arpa': 192.168.1.1Merge this into your configuration: hosts is top-level; put nameserver-policy inside the existing dns section instead of adding a duplicate section. Replace LAN addresses with your device and resolver addresses.
enhanced-mode: fake-ip returns mapped addresses; redir-host uses real answers. With fake-ip-filter-mode: blacklist, matching domains receive real IPs. With whitelist, only matching domains receive Fake IPs. Usually leave the range and TTL unchanged.
EasyTier overlay DNS on macOS
Clash Core SDK snapshot 7ea70d1 adds easytier://<node-name> for EasyTier overlay hostnames, for example easytier://Node in a nameserver-policy entry. The name must match an EasyTier outbound. This resolver is for overlay IPv4 A records and IPv4 PTR lookups, not general public DNS. The iOS/iPadOS/tvOS SDKs do not include the EasyTier implementation. See the EasyTier DNS and routing example.
Follow routing rules for DNS
Add respect-rules: true inside the existing DNS section and retain an independently reachable proxy-server-nameserver. The selected proxy must be able to connect first. Avoid casually combining this with prefer-h3.
cache-algorithm accepts lru or arc. ipv6: false affects AAAA answers, subject to the app's IP Stack setting.
Platform behavior and field status
DNS stays enabled while connected. System and DHCP sources prefer resolver addresses captured before connection; unavailable entries are filtered or repaired, and a policy losing every address may return a name error. dns.ipv6 also depends on global IPv6 and the app IP Stack setting.
DNS listen opens an additional TCP/UDP DNS service and is unnecessary for ordinary use. Proxy authentication, allow-lan, and controller secret do not provide uniform protection for it.
31 fields shown
| Field | Type | iOS | macOS | tvOS | Platform notes |
|---|---|---|---|---|---|
dns.cache-algorithm | String | Supported | Supported | Supported | Sets the DNS cache algorithm or size; use a valid algorithm name and value. |
dns.cache-max-size | Integer | Supported | Supported | Supported | Sets the DNS cache algorithm or size; use a valid algorithm name and value. |
dns.default-nameserver | List | Managed / limited | Managed / limited | Managed / limited | Sets DNS servers. system/dhcp sources use pre-connection system DNS addresses; unavailable entries are filtered or repaired. |
dns.direct-nameserver | List | Managed / limited | Managed / limited | Managed / limited | Sets direct or fallback resolvers; system/dhcp entries are replaced or filtered. Fallback is used according to its conditions. |
dns.direct-nameserver-follow-policy | Boolean | Supported | Supported | Supported | Controls whether direct DNS follows resolver policies. |
dns.enable | Boolean | Managed / limited | Managed / limited | Managed / limited | DNS stays enabled while Clash is connected; false does not disable it. |
dns.enhanced-mode | String | Supported | Supported | Supported | Selects the DNS enhancement mode; Fake IP settings apply when that mode is used. |
dns.fake-ip-filter | List | Supported | Supported | Supported | Controls which destinations use or bypass Fake IP; requires Fake IP mode. |
dns.fake-ip-filter-mode | String | Supported | Supported | Supported | Controls which destinations use or bypass Fake IP; requires Fake IP mode. |
dns.fake-ip-range | String | Supported | Supported | Supported | Sets a valid IPv4 Fake IP range; it may also supply the default tunnel IPv4 address. |
dns.fake-ip-range6 | String | Managed / limited | Managed / limited | Managed / limited | Sets the IPv6 Fake IP range; effective IPv6 settings must also enable it. |
dns.fake-ip-ttl | Integer | Supported | Supported | Supported | Sets the response TTL for Fake IP mode. |
dns.fallback | List | Managed / limited | Managed / limited | Managed / limited | Sets direct or fallback resolvers; system/dhcp entries are replaced or filtered. Fallback is used according to its conditions. |
dns.fallback-filter.domain | List | Supported | Supported | Supported | Sets fallback conditions; GeoIP/GeoSite conditions require their data resources. |
dns.fallback-filter.geoip | Boolean | Supported | Supported | Supported | Sets fallback conditions; GeoIP/GeoSite conditions require their data resources. |
dns.fallback-filter.geoip-code | String | Supported | Supported | Supported | Sets fallback conditions; GeoIP/GeoSite conditions require their data resources. |
dns.fallback-filter.geosite | List | Supported | Supported | Supported | Sets fallback conditions; GeoIP/GeoSite conditions require their data resources. |
dns.fallback-filter.ipcidr | List | Supported | Supported | Supported | Sets fallback conditions; GeoIP/GeoSite conditions require their data resources. |
dns.fallback-lazy-query | Boolean | Supported | Supported | Supported | Controls fallback DNS query scheduling; separate from lazy node health checks. |
dns.ipv6 | Boolean | Managed / limited | Managed / limited | Managed / limited | Affected by the app’s IP Stack settings; DNS IPv6 also requires global IPv6. Tunnel IPv6 capture is a separate setting. |
dns.ipv6-timeout | Integer | Supported | Supported | Supported | Controls IPv6 waiting in relevant DNS queries, not the overall VPN connection timeout. |
dns.listen | String | Advanced | Advanced | Advanced | Creates a TCP/UDP DNS listener. Proxy authentication, allow-lan, and controller secret do not provide shared access protection for it. |
dns.listen-routing-mark | Integer | Unsupported | Unsupported | Unsupported | No effect; this routing mark is not used on Apple platforms. |
dns.nameserver | List | Managed / limited | Managed / limited | Managed / limited | Sets DNS servers. system/dhcp sources use pre-connection system DNS addresses; unavailable entries are filtered or repaired. |
dns.nameserver-policy | Mapping | Managed / limited | Managed / limited | Managed / limited | Selects resolvers by domain. Addresses are also filtered; if none remain, that policy may return name-not-found. |
dns.prefer-h3 | Boolean | Supported | Supported | Supported | Prefers HTTP/3 for DNS connections that support it. |
dns.proxy-server-nameserver | List | Managed / limited | Managed / limited | Managed / limited | Sets DNS servers. system/dhcp sources use pre-connection system DNS addresses; unavailable entries are filtered or repaired. |
dns.proxy-server-nameserver-policy | Mapping | Managed / limited | Managed / limited | Managed / limited | Selects resolvers by domain. Addresses are also filtered; if none remain, that policy may return name-not-found. |
dns.respect-rules | Boolean | Supported | Supported | Supported | Routes relevant DNS requests by rules; proxy-server-nameserver does not recursively apply this setting. |
dns.use-hosts | Boolean | Supported | Supported | Supported | Uses mappings from top-level hosts for DNS queries. |
dns.use-system-hosts | Boolean | Supported | Supported | Supported | Uses system hosts readable by Clash; does not enable editing system hosts on iOS/tvOS. |
Reference: mihomo.