Mihomo DNS Configuration Guide: nameserver, fallback, and fake-IP Hijacking

Start by separating DNS upstreams, response modes, and request interception

mihomo DNS configuration has three layers: which component receives requests, which upstream handles lookups, and what address is returned to applications. nameserver and fallback manage upstream resolution; enhanced-mode determines whether clients receive real addresses or fake-IP mappings; and tun.dns-hijack routes matching DNS traffic to the built-in resolver. These layers work together, but none replaces the others.

Adding DNS server addresses to a configuration file does not mean your browser is using them. Your system may still query the router, while the browser may perform encrypted lookups through its own DoH. When troubleshooting, first confirm that requests reach mihomo; then check whether the upstream is reachable.

nameserver and default-nameserver: DNS upstreams and bootstrap resolution

nameserver is the default list of DNS upstreams. Addresses can use standard DNS or supported formats such as DoH. A standard DNS example is 223.5.5.5; a DoH example is https://dns.alidns.com/dns-query. DoH encrypts queries between your device and the resolver; it does not automatically route application traffic through a proxy.

Why use default-nameserver?

When an upstream address is a hostname, the core needs its IP address before it can connect. For example, it must resolve dns.alidns.com before connecting to it. default-nameserver handles this bootstrap lookup. Using explicit IP addresses avoids a loop in which the DNS server must be resolved by that same server.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: redir-host
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://doh.pub/dns-query

• 127.0.0.1:1053 listens only on the local machine; it does not expose DNS to devices on your LAN.
• redir-host returns the resolved IP address to applications, making it a useful baseline for initial connectivity tests.
• ipv6: false makes the built-in DNS return empty results for AAAA queries. It does not disable IPv6 in the operating system or stop applications from connecting directly to known IPv6 addresses.
• Do not assume that multiple upstreams are queried strictly in the order listed. Avoid relying on their order to route domains to different resolvers.

This is a standalone dns configuration example; it does not include proxy nodes or rules. Merge it into your existing configuration instead of replacing the entire subscription. If your network blocks a resolver, use an upstream that is reachable from your current network.

fallback and fallback-filter: filter results, not just a backup

The name fallback can make it sound as if it runs only when nameserver fails. In practice, once fallback is configured, the core can query both upstream groups in parallel and use fallback-filter to decide which results to accept. Seeing fallback queries during normal browsing does not necessarily mean the primary upstream has failed.

A common setup uses the primary upstream for results suited to the local network. For domains assigned to fallback—or when the primary returns an address that fails the filter—the fallback result is used instead. This selects between DNS responses; subsequent connections are still matched against proxy rules.

Example: filter by GeoIP and IP ranges

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: redir-host
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query
  fallback:
    - https://dns.google/dns-query
    - https://cloudflare-dns.com/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN
    ipcidr:
      - 240.0.0.0/4
    domain:
      - '+.google.com'

• Together, geoip: true and geoip-code: CN use GeoIP data to check whether an address returned by the primary upstream belongs to the specified region. If it does not, the fallback result is preferred.
• If an address returned by the primary upstream matches the ipcidr list, mihomo uses fallback. The 240.0.0.0/4 in this example is an address filter, not a proxy-node subnet or TUN address pool.
• Domains matching domain use the fallback result directly. +.google.com matches the domain and its subdomains.
• GeoIP decisions depend on the data used by the core. An outdated database or a CDN deployed across regions can produce results that differ from expectations.

Do not treat every private IP address as a polluted result. An internal corporate domain resolving to 10.0.0.0/8 or a home device resolving to 192.168.0.0/16 can be entirely normal. Adding all these ranges to ipcidr may send internal domains to public DNS instead. For known internal domains, use targeted resolution rather than broadening the fallback filter.

fake-ip and redir-host: return a mapped address or the real address

With enhanced-mode: fake-ip, mihomo assigns each domain a mapped address from the configured pool. When an application connects to that address, traffic reaches mihomo, which recovers the domain from the mapping and matches it against the rules. This reduces reliance on applications receiving real IP addresses from DNS—but only if those connections are actually intercepted by the core.

redir-host returns the real resolved address and tracks the associated domain information. It behaves more like conventional DNS, but domains and addresses do not always map one-to-one. How mihomo identifies a domain for a connection also depends on interception, caching, and sniffing settings. Neither mode replaces correctly configured proxy rules.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - localhost
    - '*.lan'
    - '*.local'
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://doh.pub/dns-query

Which domains belong in fake-ip-filter?

In the usual blacklist filtering mode, domains matching fake-ip-filter are not assigned fake IPs; mihomo returns their real addresses instead. This example shows exceptions for local hostnames and LAN names. If your configuration sets fake-ip-filter-mode differently, check that mode first—the behavior described here may not apply.

• For LAN device discovery, some games, or applications that require real IPs, add exceptions for specific domains instead of using an overly broad wildcard.
• Filtering changes only the DNS response; it does not automatically send printer.lan to your router. Internal names still need a local upstream that can resolve them.
• .local is often associated with mDNS. Adding it to the filter does not make mihomo proxy multicast discovery or fix screen casting automatically.
• Do not assume DNS is polluted just because you see 198.18.x.x. In this example, that is an expected fake-IP response. The real test is whether the connection reaches the core and the domain can be recovered.

After switching from fake-ip to redir-host, or vice versa, clear the system DNS cache and restart the application you are testing. If the browser still has an old mapped address cached, it may keep using that address even after the configuration changes.

TUN DNS hijacking: send port 53 requests to the built-in resolver

“fake-IP hijacking” often conflates two separate concepts: fake-IP is a response mode, while DNS hijacking redirects requests. The top-level tun snippet below can be combined with one of the preceding dns examples to intercept matching UDP and TCP requests on port 53 that enter TUN.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53
    - tcp://any:53

any:53 matches UDP DNS, while tcp://any:53 matches TCP DNS. Port 53 is the destination port of the traffic being matched; 1053 in dns.listen above is the local listening port used for testing. They do not need to match. The core forwards matching requests to its built-in DNS—it does not require the system to connect directly to port 1053 first.

Traffic that may still bypass interception

1. Browser DoH: Usually uses HTTPS on port 443, so it is not a standard port 53 query. You can temporarily disable Secure DNS in your browser while diagnosing, then re-enable it if needed.
2. DoT built into apps: Commonly uses destination port 853. The two rules above do not convert it into a built-in DNS query.
3. Traffic that never enters TUN: Route exclusions, another VPN, network interface selection, and platform limitations can all bypass the interception path.
4. LAN devices: Enabling TUN on a computer does not make it the DNS gateway for your entire network. Configure the gateway, DNS, and forwarding path separately for other devices.

With system proxy mode alone, a browser's HTTP requests may use the proxy while system DNS still goes to the router. This does not mean dns.enable has failed; the requests simply have not reached the built-in resolver. Choose an explicit approach for your setup, such as pointing system DNS to mihomo, using TUN interception, or configuring another redirection method.

Targeted DNS for internal domains and proxy node hostnames

A home NAS, company intranet services, and public domains usually should not share the same DNS path. mihomo's nameserver-policy can assign upstreams by domain and takes priority over the general nameserver and fallback setup. Merge the snippet below under your existing dns section. It assumes the router is actually at 192.168.1.1.

  nameserver-policy:
    '+.home.arpa':
      - 192.168.1.1
  proxy-server-nameserver:
    - https://dns.alidns.com/dns-query

home.arpa is used for local domain names on home networks. If your router has no matching records, a policy cannot create DNS results out of thin air. With fake-ip, if an application needs the real internal address, add the domain to an appropriate fake-IP filter rule as well.

proxy-server-nameserver resolves the hostnames of proxy servers themselves; it does not resolve every website accessed through a proxy. Providing a directly reachable resolver for proxy nodes reduces the risk of a dependency loop where DNS needs a proxy while the proxy needs DNS to connect.

When DNS should follow proxy rules

respect-rules: true makes connections to DNS upstreams follow routing rules. When using it, also configure proxy-server-nameserver and check which rule is ultimately selected. This is not a universal fix for resolution failures. If resolving a node hostname, connecting to an upstream, and selecting a rule all depend on one another, the setup can fail to start even when each address looks correct on its own.

Verify the setup in four steps: listening, resolution, interception, and rules

Keep a rollback-ready copy of your configuration and change one layer at a time. Start with redir-host to verify real DNS resolution, then test fake-ip, and only then add fallback or DNS egress rules. This makes issues easier to pinpoint than enabling everything at once.

Step 1: Confirm that the YAML loaded

• Keep only one dns: key at each level. Duplicate keys may trigger an error or cause the later section to overwrite the earlier one.
• Use spaces for indentation, not tabs. tun: and dns: are sibling keys; do not indent the entire TUN section under DNS.
• Subscription updates may overwrite local changes. Put persistent settings in a client-supported override mechanism, then check the effective configuration after each update.

Step 2: Query the local port 1053 directly

On macOS or Linux with dig installed, run the two commands below to test UDP and TCP separately. If the tool is unavailable, install it using your system's package manager or use another DNS query tool that supports a custom port.

dig @127.0.0.1 -p 1053 example.com A
dig @127.0.0.1 -p 1053 example.com A +tcp

In redir-host mode, the response should contain the real resolved address. In fake-ip mode, domains that are not filtered usually return a mapped address from the configured pool. If both commands time out, check the listener on port 1053, whether the configuration loaded, and the local firewall before changing proxy rules. If you get SERVFAIL, check the logs for bootstrap resolution, upstream connectivity, and certificate verification issues.

Step 3: Check whether system queries reach the core

On Windows, run ipconfig /flushdns to clear the system DNS cache. On Linux with systemd-resolved, run resolvectl flush-caches. Then close and reopen the test browser to reduce interference from its own cache. If a direct query to port 1053 succeeds but regular app traffic fails, focus on TUN routing and app-specific DNS.

Step 4: Tell DNS success apart from connection success

Check the client's connection log for the destination domain, matched rule, outbound policy, and errors. A DNS response confirms only that resolution completed; an unreachable node, a rule selecting the wrong outbound, or a blocked destination port can still prevent a website from loading. Recovering a domain from a fake-IP address also does not prove that the selected proxy node is available.

To troubleshoot system proxy, ports, or TUN, see Troubleshooting. For the steps to import a subscription for the first time or switch modes, see the setup guide. DNS settings should fit your current network path, not simply add more resolvers.