DNS

Egern's DNS provides support for multiple protocols, including traditional DNS, DNS over HTTPS, DNS over TLS, and DNS over QUIC. Users can configure forwarding rules to direct specific domain requests to different DNS servers.

Bootstrap (Default DNS Servers)

Egern uses the system-configured DNS servers by default, i.e., the DNS servers from your Wi-Fi or cellular network. This server only supports the traditional DNS protocol and is used to resolve the domain names of DNS servers configured in Upstreams, as well as serving as the default DNS server when no forward rules are matched. DNS servers configured in Bootstrap do not follow proxy rules; traffic connects directly to the server.

Upstreams (DNS Server Groups)

Upstreams configuration includes DNS servers using traditional DNS protocol, DNS over HTTPS, DNS over TLS, and DNS over QUIC. The key is the group name, and the value is a list of servers.

Supported server formats:

• UDP DNS: 1.1.1.1, 1.1.1.1:53
• DNS over TLS: tls://1.1.1.1
• DNS over HTTPS: https://8.8.8.8/dns-query
• DNS over QUIC: quic://dns.adguard-dns.com
• Special value bootstrap: uses the bootstrap DNS server
• Special value system: uses the system DNS server

Forward (DNS Forwarding Rules)

Forward is used to define DNS forwarding rules. Each rule consists of a domain matching condition and an upstream DNS group. The following match types are supported:

Type	Description
domain	Exact domain match
domain_keyword	Domain keyword match
domain_suffix	Domain suffix match
domain_wildcard	Wildcard match (e.g., *.google.com)
domain_regex	Regular expression match
proxy_rule_set	Match using a proxy rule set
ssid	Wi-Fi SSID match (e.g., MyHome*)
bssid	Wi-Fi BSSID match (e.g., AA:BB:CC:*)
cellular	Cellular network type match (e.g., LTE, NR)

Each rule contains the following fields:

• match (string), required

  The match condition.

• value (string), required

  The upstream DNS group name or server address. Supports group names defined in upstreams, DNS server addresses, the special value reject (refuse resolution), bootstrap (use the bootstrap DNS), and system (use the system DNS).

• disabled (bool), optional

  Whether this rule is disabled.

• update_interval (integer), optional

  Rule set update interval (in seconds), only effective for the proxy_rule_set type. Default is 86400 seconds.

Hosts (Host Mapping)

Hosts is used to map hostnames to IP addresses or other hostnames. The key is a glob wildcard pattern used to match domain names or IP addresses (e.g., *.google.com, 192.168.1.*). The value can be an IP address or a domain name, supporting either a single value or an array of multiple values.

hosts:
  "*.google.com": 142.250.80.46        # Wildcard matching domain, mapped to IP
  "example.com": www.example.com       # Domain mapped to another domain
  "192.168.1.100": internal.example.com  # IP match, mapped to domain
  "cdn.example.com":                   # Mapped to multiple IPs
    - 1.2.3.4
    - 5.6.7.8

Block IPs

Used to filter IP addresses from DNS responses (to prevent DNS poisoning). Records matching these IPs in DNS responses will be filtered out. Resolution is only considered failed when all records have been filtered. Supports IPv4, IPv6 addresses, and CIDR notation (e.g., 10.0.0.0/8).

Public IP Lookup URL

This URL is used to query the device's public IP address and serves as a parameter for EDNS Client Subnet, helping DNS servers provide domain resolution results closest to the device's public IP. The response content should be a plain-text IP address.

Configuration Example

dns:
  bootstrap:
    - system  # Use the system default DNS configuration as bootstrap
  upstreams:
    google:
      - https://8.8.8.8/dns-query
      - https://8.8.4.4/dns-query
    adguard:
      - quic://dns.adguard-dns.com
  forward:
    - domain:
        match: "internal.example.com"
        value: "192.168.1.1"
    - domain_suffix:
        match: "cn"
        value: bootstrap
    - domain_keyword:
        match: "taobao"
        value: bootstrap
    - domain_wildcard:
        match: "*.cn"
        value: bootstrap
    - proxy_rule_set:
        match: "https://example.com/china-domains.list"
        value: bootstrap
        update_interval: 86400
    - domain_regex:
        match: "^ad\\..*|^ads\\..*"
        value: reject
    - ssid:
        match: "MyHome*"
        value: bootstrap
    - bssid:
        match: "AA:BB:CC:*"
        value: bootstrap
    - cellular:
        match: "NR"
        value: google
    - domain_wildcard:
        match: "*"
        value: google
  hosts:
    example.com: www.example.com
    localhost: 127.0.0.1
    "*.local": 192.168.1.1
  block_ips:
    - 1.2.3.4
    - 4.3.2.1/32
  public_ip_lookup_url: https://ifconfig.me/ip

FAQ

Why is a Bootstrap DNS server needed when Upstreams are already configured?

This is because resolving the domain names of DNS servers configured in Upstreams may require the Bootstrap DNS server to complete the initial resolution.