6. DNS and hosts#

DNS is central to transparent proxying and TUN. Many cases where "rules do not take effect" are essentially because Link1 did not obtain the domain name.

Minimal DNS Configuration#

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - https://223.5.5.5/dns-query
    - tls://223.5.5.5:853

Practical impact:

• enable=true enables the Link1 DNS resolver.

• listen starts a local DNS service for the system or router to forward queries to.

• enhanced-mode=fake-ip improves domain-rule hit rates in transparent proxy scenarios.

• nameserver is the default upstream DNS.

DNS Server Syntax#

Link1 supports the following DNS upstream formats:

DoH can specify HTTP/3 through a URL fragment:

nameserver:
  - https://dns.google/dns-query#h3=true

You can also use a fragment to select a routing egress:

nameserver:
  - https://dns.google/dns-query#PROXY

DNS Field Reference#

Fake-IP#

How Fake-IP works:

The client queries api.example.com
  -> Link1 returns 198.18.0.10
Client connection 198.18.0.10:443
  -> Link1 reverse-maps 198.18.0.10 to api.example.com
  -> Domain rules can match

Suitable for:

• TUN.

• Transparent proxying.

• Router gateway mode.

Not suitable for, or should be filtered for:

• Some LAN device connectivity-check domains.

• Service discovery that depends on real IPs.

• Internal domains.

Example:

dns:
  enhanced-mode: fake-ip
  fake-ip-filter:
    - '*.lan'
    - '+.local'
    - 'dns.msftnsci.com'

nameserver-policy#

Specify different DNS upstreams by domain:

dns:
  nameserver:
    - https://dns.google/dns-query
  nameserver-policy:
    '+.corp.example.com':
      - openvpn://corp-vpn
    '+.tailnet.ts.net':
      - ts://tailnet
    'geosite:cn':
      - https://223.5.5.5/dns-query
    'rule-set:private':
      - system://

Practical impact:

• Enterprise domains can use enterprise VPN DNS.

• Tailnet domains can use Tailscale MagicDNS; tailscale://name and ts://name are equivalent.

• Domestic domains can use domestic DNS.

• Specific rulesets can use dedicated DNS.

• Policy keys support comma-separated values, for example geosite:cn,private.

fallback-filter#

dns:
  fallback:
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN
    geosite:
      - geolocation-!cn
    domain:
      - '+.google.com'
    ipcidr:
      - 240.0.0.0/4

Meaning: when the default DNS returns an unexpected result, use the fallback result. A common use case is reducing the impact of DNS pollution.

Field impact:

hosts#

Static hosts:

hosts:
  router.lan: 192.168.9.1
  api.local:
    - 10.0.0.10
    - 10.0.0.11

Practical impact:

• Takes precedence over upstream DNS.

• Suitable for internal services, test domains, and fixed mappings.

• If dns.use-hosts=false, hosts in the configuration does not take effect.

hosts-providers#

Load hosts from an external file or URL:

hosts-providers:
  intranet:
    type: file
    path: ./hosts/intranet.hosts

  remote-hosts:
    type: http
    url: https://example.com/hosts.txt
    path: ./hosts/remote.hosts
    interval: 3600
    proxy: DIRECT

Field impact:

Relationship Between DNS and Rules#

Domain rules depend on domain context, and IP rules depend on IP context. For TUN/transparent proxying, the following is recommended:

dns:
  enable: true
  enhanced-mode: fake-ip

tun:
  enable: true
  dns-hijack:
    - any:53

sniffer:
  enable: true

This lets the rule engine obtain both domain and IP information as much as possible.