DNS - Simple DNS Client and Server

Installation

As a Library

To install the package, run:

go get github.com/go-zoox/dns

As a CLI Tool

To build and install the CLI tool:

go build -o bin/dns ./cmd/dns
# Or install globally
go install ./cmd/dns

CLI Usage

DNS Client Query

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

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

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

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

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 --doh-port 443 --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem

# Start DNS server with DoQ support
dns server --port 53 --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

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:
  "example.com": "1.2.3.4"
  "www.example.com":
    - "1.2.3.4"
    - "1.2.3.5"
  "dual.example.com":
    a: ["1.2.3.4"]
    aaaa: ["2001:db8::1"]

# 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
• Priority: Custom hosts are checked before upstream DNS servers
• Override: Command line flags override config file values

Getting Started

Basic DNS Server

func main() {
	server := dns.NewServer(&dns.ServerOptions{
		Port: 53,
	})
	client := dns.NewClient()

	server.Handle(func(host string, typ int) ([]string, error) {
		key := fmt.Sprintf("%s_%d", host, typ)

		if host == "gozoox.com" {
			return []string{"6.6.6.6"}, nil
		}

		if ips, err := client.LookUp(host, &dns.LookUpOptions{Typ: typ}); err != nil {
			return nil, err
		} else {
			logger.Info("found host(%s %d) %v", host, typ, ips)
			return ips, nil
		}
	})

	server.Serve()
}

DNS-over-TLS (DoT) Client

import (
	"github.com/go-zoox/dns"
	"github.com/go-zoox/dns/client"
)

// Use DoT server
client := dns.NewClient(&dns.ClientOptions{
	Servers: []string{"tls://1.1.1.1"}, // Cloudflare DoT
	Timeout: 10 * time.Second,
})

// Lookup with DoT
ips, err := client.LookUp("example.com")
if err != nil {
	log.Fatal(err)
}
fmt.Println("IPs:", ips)

DNS-over-TLS (DoT) Server

import (
	"github.com/go-zoox/dns"
)

// Create DoT server with TLS certificate
server := dns.NewServer(&dns.ServerOptions{
	Port:        53,  // Plain DNS port
	DoTPort:     853, // DoT port (default)
	EnableDoT:   true,
	TLSCertFile: "/path/to/cert.pem",
	TLSKeyFile:  "/path/to/key.pem",
})

// Or use tls.Config directly
tlsConfig := &tls.Config{
	Certificates: []tls.Certificate{cert},
}
server := dns.NewServer(&dns.ServerOptions{
	Port:       53,
	DoTPort:    853,
	EnableDoT:  true,
	TLSConfig:  tlsConfig,
})

server.Handle(func(host string, typ int) ([]string, error) {
	// Your DNS resolution logic
	return []string{"1.2.3.4"}, nil
})

server.Serve()

DNS-over-HTTPS (DoH) Server

import (
	"github.com/go-zoox/dns"
)

// Create DoH server with TLS certificate
server := dns.NewServer(&dns.ServerOptions{
	Port:        53,  // Plain DNS port
	DoHPort:     443, // DoH port (default)
	EnableDoH:   true,
	TLSCertFile: "/path/to/cert.pem",
	TLSKeyFile:  "/path/to/key.pem",
})

// Or use tls.Config directly
tlsConfig := &tls.Config{
	Certificates: []tls.Certificate{cert},
}
server := dns.NewServer(&dns.ServerOptions{
	Port:       53,
	DoHPort:    443,
	EnableDoH:  true,
	TLSConfig:  tlsConfig,
})

server.Handle(func(host string, typ int) ([]string, error) {
	// Your DNS resolution logic
	return []string{"1.2.3.4"}, nil
})

server.Serve()

DoH server supports both GET and POST methods:

• GET: https://your-server:443/dns-query?dns=<base64url-encoded-dns-message>
• POST: https://your-server:443/dns-query with Content-Type: application/dns-message

DNS-over-QUIC (DoQ) Server

import (
	"github.com/go-zoox/dns"
)

// Create DoQ server with TLS certificate
server := dns.NewServer(&dns.ServerOptions{
	Port:        53,  // Plain DNS port
	DoQPort:     853, // DoQ port (default)
	EnableDoQ:   true,
	TLSCertFile: "/path/to/cert.pem",
	TLSKeyFile:  "/path/to/key.pem",
})

// Or use tls.Config directly
tlsConfig := &tls.Config{
	Certificates: []tls.Certificate{cert},
}
server := dns.NewServer(&dns.ServerOptions{
	Port:       53,
	DoQPort:    853,
	EnableDoQ:  true,
	TLSConfig:  tlsConfig,
})

server.Handle(func(host string, typ int) ([]string, error) {
	// Your DNS resolution logic
	return []string{"1.2.3.4"}, nil
})

server.Serve()

Features

Client

• 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.

License

GoZoox is released under the MIT License.