DNS Server

The DNS server allows you to run your own DNS server with custom host mappings and upstream DNS fallback.

Basic Usage

Start Basic Server

Start a DNS server on the default port 53:

dns server --port 53

Start with Custom Port

dns server --port 5353

Options

--port

DNS server port. Default: 53.

dns server --port 5353

--host

Listen address. Default: 0.0.0.0.

dns server --host 127.0.0.1 --port 53

--upstream

Upstream DNS server. Can be specified multiple times. Supports:

• Plain DNS: 8.8.8.8:53
• DNS-over-TLS: tls://1.1.1.1
• DNS-over-HTTPS: https://dns.adguard.com/dns-query

dns server --port 53 --upstream 8.8.8.8:53 --upstream tls://1.1.1.1

--config

Path to configuration file. See Configuration for details.

dns server --config /path/to/config.yaml

--dot

Enable DNS-over-TLS (DoT) server.

dns server --port 53 --dot --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem

--tls-cert / --tls-key

TLS certificate and key files for DoT, DoH, and DoQ servers.

dns server --dot --tls-cert cert.pem --tls-key key.pem

--dot-port

DoT server port. Default: 853.

dns server --dot --dot-port 853 --tls-cert cert.pem --tls-key key.pem

--doh

Enable DNS-over-HTTPS (DoH) server.

dns server --port 53 --doh --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem

--doh-port

DoH server port. Default: 443.

dns server --doh --doh-port 443 --tls-cert cert.pem --tls-key key.pem

--doq

Enable DNS-over-QUIC (DoQ) server.

dns server --port 53 --doq --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem

--doq-port

DoQ server port. Default: 853.

dns server --doq --doq-port 853 --tls-cert cert.pem --tls-key key.pem

--ttl

TTL for DNS responses in seconds. Default: 500.

dns server --port 53 --ttl 300

--disable-system-hosts

Disable system hosts file lookup.

dns server --port 53 --disable-system-hosts

--system-hosts-file

Path to system hosts file. Default: /etc/hosts.

dns server --port 53 --system-hosts-file /custom/hosts

Response cache (upstream answers)

Caches final A/AAAA answers that required upstream (including config/system alias chains). Static hosts and /etc/hosts IP hits are not cached and are always evaluated first.

Flag	Default	Description
--disable-cache	off	Disable response cache (DNS_DISABLE_CACHE=true)
--cache-ttl	300s	TTL when the answer has at least one IP (DNS_CACHE_POSITIVE_TTL)
--cache-negative-ttl	60s	TTL for empty / NXDOMAIN-style answers (DNS_CACHE_NEGATIVE_TTL)
--cache-max-entries	10000	Max entries (DNS_CACHE_MAX_ENTRIES)

With a config file, YAML cache.* overrides these defaults unless you set the corresponding flag explicitly on the CLI. --disable-cache wins over cache.enabled: true.

# Cache is on by default; tune TTLs:
dns server --port 53 --upstream 8.8.8.8:53 --cache-ttl 10m --cache-negative-ttl 120s
dns server --disable-cache

See Configuration for the cache: YAML block.

Command Line Flags Override Config File

Command line flags take precedence over configuration file values:

# config.yaml has port: 53, but command line overrides it
dns server --config config.yaml --port 5353

Examples

Basic Server with Upstream

dns server --port 53 --upstream 8.8.8.8:53

Server with DoT

dns server --port 53 --dot --tls-cert cert.pem --tls-key key.pem

Server with DoH

dns server --port 53 --doh --tls-cert cert.pem --tls-key key.pem

Server with DoQ

dns server --port 53 --doq --tls-cert cert.pem --tls-key key.pem

Server with Multiple Protocols

# Enable all protocols (DoT, DoH, DoQ)
dns server --port 53 \
  --dot --dot-port 853 \
  --doh --doh-port 443 \
  --doq --doq-port 853 \
  --tls-cert cert.pem --tls-key key.pem

Server with Configuration File

dns server --config config.yaml

Next Steps

• Configuration - Learn about configuration options
• DNS-over-TLS (DoT) - Learn about DoT server setup
• DNS-over-HTTPS (DoH) - Learn about DoH server setup
• DNS-over-QUIC (DoQ) - Learn about DoQ server setup
• Examples - See more examples