dns

README

CLI for DNS - Simple DNS Client and Server

Installation

Install CLI Tool

go install github.com/go-idp/dns/cmd/dns@latest

Or build from source:

git clone https://github.com/go-idp/dns.git
cd dns
go build -o bin/dns ./cmd/dns

CLI Usage

DNS Client (lookup / stress)

# Query A record
dns client lookup google.com --type A

# Query AAAA record (IPv6)
dns client lookup google.com --type AAAA

# Use DoT server
dns client lookup example.com --server tls://1.1.1.1

# Use DoH server
dns client lookup example.com --server https://cloudflare-dns.com/dns-query

# Use DoQ server
dns client lookup example.com --server quic://dns.adguard.com

# Use custom timeout
dns client lookup example.com --timeout 10s

# Plain DNS load test (UDP/TCP only; use host or host:port, not tls:// / https://)
dns client stress --domain example.com --server 127.0.0.1:5353 --workers 200 --requests 5000
dns client stress --domain example.com --server 8.8.8.8 --net tcp --workers 50 -n 500

DNS Server

# Start basic DNS server
dns server --port 53

# Start DNS server with DoT support
dns server --port 53 --dot --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem

# Start DNS server with DoH support
dns server --port 53 --doh --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem

# Start DNS server with DoQ support
dns server --port 53 --doq --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem

# Start DNS server with all protocols (DoT, DoH, DoQ)
dns server --port 53 \
  --dot --dot-port 853 \
  --doh --doh-port 443 \
  --doq --doq-port 853 \
  --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem

# Start DNS server with custom upstream
dns server --port 53 --upstream 8.8.8.8:53 --upstream 1.1.1.1:53

# Start DNS server with configuration file
dns server --config /path/to/config.yaml

# Command line flags override config file values
dns server --config /path/to/config.yaml --port 5353

High QPS: successful answers are logged at debug only; raise the logger to debug when troubleshooting. Tune upstream.servers and upstream.timeout. Response cache is on by default for upstream-derived answers; turn it off with dns server --disable-cache or cache.enabled: false in YAML.

Configuration File

The server supports YAML configuration files for easier management. See example/conf/server.yaml for a complete example.

Configuration File Structure:

# Basic server settings
server:
  host: "0.0.0.0"
  port: 53
  ttl: 500

# DNS-over-TLS (DoT) configuration
dot:
  enabled: false
  port: 853
  tls:
    cert: "/path/to/cert.pem"
    key: "/path/to/key.pem"

# DNS-over-HTTPS (DoH) configuration
doh:
  enabled: false
  port: 443
  tls:
    cert: "/path/to/cert.pem"
    key: "/path/to/key.pem"

# DNS-over-QUIC (DoQ) configuration
doq:
  enabled: false
  port: 853
  tls:
    cert: "/path/to/cert.pem"
    key: "/path/to/key.pem"

# Custom domain mappings (highest priority)
hosts:
  # Simple format: single domain to single IP (backward compatible)
  "example.com": "1.2.3.4"
  
  # Alias target (CNAME-like flattening):
  # If value is not an IP, it is treated as an alias target domain.
  # Querying A/AAAA for mysql.ops.ys.idp.internal will resolve
  # db.tencentcloud.com via upstream and return final IPs.
  "mysql.ops.ys.idp.internal": "db.tencentcloud.com"

  # Explicit alias format (extension)
  "redis.ops.ys.idp.internal":
    cname: "redis.tencentcloud.com"

  "www.example.com":
    - "1.2.3.4"
    - "1.2.3.5"
  "dual.example.com":
    a: ["1.2.3.4"]
    aaaa: ["2001:db8::1"]
  
  # Wildcard pattern: matches any subdomain
  "*.example.com": "1.2.3.4"
  
  # Regex pattern: matches domains using regular expressions
  "^mp-\\w+\\.example\\.com$": "1.2.3.4"

# Optional: tune in-memory cache (on by default; omit cache section to use defaults).
# Set enabled: false to disable. Defaults: positive_ttl 300s, negative_ttl 60s, max_entries 10000.
# cache:
#   enabled: false

# Upstream DNS servers
upstream:
  servers:
    - "114.114.114.114:53"
    - "tls://1.1.1.1"
  timeout: "5s"

Key Features:

• Custom Hosts Mapping: Define custom domain-to-IP mappings with highest priority
• Multiple IP Support: Support multiple IPv4 and IPv6 addresses per domain
• Flexible Format: Support simple string, list, or structured format
• Alias Support: String domain values or cname field map local names to upstream domains (returns A/AAAA IPs)
• Wildcard Patterns: Use *.example.com to match any subdomain
• Regex Patterns: Use regular expressions like ^mp-\\w+\\.example\\.com$ for advanced matching
• System Hosts File: Support for /etc/hosts with wildcard and regex patterns (enabled by default)
• Priority: Custom hosts are checked before system hosts and upstream DNS servers
• Override: Command line flags override config file values

Getting Started

Quick Start

After installation, you can start using the DNS CLI:

# Query a domain
dns client lookup google.com

# Start a DNS server
dns server --port 53

See the documentation for more examples and detailed usage.

Features

Client

• lookup: resolve A/AAAA via plain DNS, DoT, DoH, DoQ, DNSCrypt
• stress: concurrent plain DNS (UDP/TCP) load test against one server
• Plain DNS
  • Plain DNS in UDP
  • Plain DNS in TCP
• DNS-over-TLS (DoT) - Use tls:// prefix (e.g., tls://1.1.1.1)
• DNS-over-HTTPS (DoH)
• DNS-over-QUIC (DoQ)
• DNSCrypt

Server

• Plain DNS
  • Plain DNS in UDP
  • Plain DNS in TCP
• DNS-over-TLS (DoT)
• DNS-over-HTTPS (DoH)
• DNS-over-QUIC (DoQ)

Inspired By

• AdGuardHome - Network-wide ads & trackers blocking DNS server.
• kenshinx/godns - A fast dns cache server written by go.
• miekg/dns - DNS library in Go.

Documentation

Full documentation is available at: https://go-idp.github.io/dns/

License

MIT License - see LICENSE for details.

Documentation

Index

• Variables

Variables

var Version = "1.4.5"

Version is the version of dns