# Dns

> DNS override, local mapping, encrypted DNS

[← Back to index](/llms.txt)

---

## Dns override

# DNS Server

Surge implements a specialized DNS client with advanced capabilities that may differ from standard operating system DNS clients.

## Upstream DNS Server

By default, Surge retrieves DNS servers from your system settings. You can customize this with the `dns-server` parameter:

```
[General]
dns-server = 8.8.8.8, 8.8.4.4
```

To supplement system settings with additional servers, use the `system` keyword:

```
[General]
dns-server = system, 8.8.8.8, 8.8.4.4
```

(Duplicate entries are automatically filtered out)

## Technical Details

Surge queries all configured DNS servers simultaneously to optimize performance. It uses the first answer from servers rather than sequential querying. If no response arrives within 2 seconds, Surge retries all servers. After four retry attempts, the client reports a DNS error.

When domains have underperforming authoritative servers, upstream DNS providers may timeout or fail to respond. Surge reports an empty result only if all servers explicitly return empty answers, or if some return empty while others timeout beyond the 2-second window.

IPv6-enabled systems receive both A and AAAA record queries. The first A or AAAA answer returned will be used.


## Doh

# Encrypted DNS

If encrypted DNS is configured, traditional DNS is only used to test connectivity and resolve the domain in the encrypted DNS URL.

## Supported Protocols

- DNS over HTTPS: `https://example.com`
- DNS over HTTP/3: `h3://example.com`
- DNS over QUIC: `quic://example.com`

## Use Encrypted DNS for All Domains

```
[General]
encrypted-dns-server = https://8.8.8.8/dns-query
```

Multiple encrypted servers can be specified and separated by commas.

## Use Encrypted DNS for Specified Domains

```
[Host]
example.com = server:https://cloudflare-dns.com/dns-query
```

## Use Encrypted DNS with Proxy

To route DoH queries through a proxy, set `encrypted-dns-follow-outbound-mode` to true:

```
[General]
encrypted-dns-follow-outbound-mode=true
```

All encrypted DNS connections will follow the outbound mode settings. Configure a rule for the DoH hostname to use a proxy.

Alternatively, use `PROTOCOL,DOH`, `PROTOCOL,DOH3` or `PROTOCOL,DOQ` rules to match all encrypted DNS connections.


## Local dns mapping

# Local DNS Mapping

Surge supports customized DNS mapping functionality. It functions similarly to `/etc/hosts` but with enhanced capabilities like wildcards, domain aliases, and custom DNS server assignments.

## Basic Syntax

The configuration uses a `[Host]` section with simple key-value pairs:

```
[Host]
abc.com = 1.2.3.4
*.dev = 6.7.8.9
foo.com = bar.com
bar.com = server:8.8.8.8
```

## Wildcard Support

The system supports asterisk prefixes to match subdomains. However, matching uses basic string comparison, so `*google.com` matches `google.com`, `foo.google.com`, and `bargoogle.com`, while `*.google.com` does not match the root domain.

## Domain Aliases

You can create alias mappings similar to CNAME records by pointing one domain to another.

## Custom DNS Server Assignment

Domains can be configured to resolve through specific DNS servers using the `server:` syntax. Special options include:
- `server:system` — delegates to the operating system's resolver
- `server:syslib` — routes queries through macOS DNS servers while staying within Surge
- By default, domains ending in `.local` resolve via the system

## Remote Rule Set Integration

Entire `DOMAIN-SET` or `RULE-SET` files can be bound to DNS mappings, allowing shared upstream or IP assignments without manual duplication.

## Proxy-Specific DNS Handling

Enabling `use-local-host-item-for-proxy=true` in the `[General]` section allows Surge to use locally-mapped IP addresses for proxy requests instead of forwarding domain names to remote servers.