Configuration Reference

All options for /etc/domudns/config.yaml. Environment variables override config file values.

cluster

Controls the node's role in the cluster and data storage location.

yaml
cluster:
  role: "master"                    # "master" | "slave"
  data_dir: "/var/lib/domudns/data" # JSON data directory
  slaves:                           # Master only: slave URLs
    - "http://192.0.2.2:80"
  master_url: ""                    # Slave only: master URL
  sync_interval: "30s"              # Slave poll interval (fallback)

Key	Default	Description
`role`	`"master"`	Node role. Standalone = master without slaves.
`data_dir`	`"/var/lib/domudns/data"`	Path for JSON zone and config files.
`slaves`	`[]`	List of slave HTTP URLs (master only).
`master_url`	`""`	Master HTTP URL for polling (slave only).
`sync_interval`	`"30s"`	Slave poll interval as fallback for push failures.

dnsserver

yaml
dnsserver:
  listen: "[::]:53"           # UDP+TCP listener (IPv4+IPv6)
  upstream:                   # Upstream DNS resolvers
    - "9.9.9.9"
    - "149.112.112.112"
  block_mode: "nxdomain"      # "nxdomain" | "zero_ip" | "refused"
  rebinding_protection: true  # Block external → private IP
  dot:
    enabled: false
    listen: ":853"
    cert_file: "/etc/domudns/cert.pem"
    key_file:  "/etc/domudns/key.pem"

Key	Default	Description
`listen`	`"[::]:53"`	DNS listener address. Dual-stack (IPv4+IPv6).
`upstream`	`["9.9.9.9"]`	Upstream resolvers. Live-reloadable via API.
`block_mode`	`"nxdomain"`	Response for blocked domains.
`rebinding_protection`	`true`	Blocks SSRF via DNS rebinding attacks.

http

yaml
http:
  listen: ":80"
  doh:
    enabled: false            # DNS over HTTPS (RFC 8484)
    path: "/dns-query"

blocklist

yaml
blocklist:
  default_urls:               # Applied only when blocklist store is empty
    - "https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts"
    - "https://adaway.org/hosts.txt"
  update_interval: "24h"      # Re-fetch interval (master/standalone only)
  whitelist_ips:              # IPs that bypass blocklist
    - "192.168.1.0/24"

Note: Blocklist fetching only runs on master/standalone nodes. Slaves receive the blocklist via cluster push.

cache

yaml
cache:
  enabled: true
  max_size: 10000             # Max cached entries (LRU eviction)
  min_ttl: 60                 # Minimum TTL in seconds
  max_ttl: 3600               # Maximum TTL cap
  negative_ttl: 30            # TTL for NXDOMAIN answers
  warmup_enabled: true        # Pre-warm cache on startup
  warmup_count: 200           # Number of popular domains to pre-warm

system

yaml
system:
  log_level: "info"           # "debug" | "info" | "warn" | "error"
  metrics:
    enabled: true
    listen: ":9090"           # Prometheus metrics endpoint
  rate_limit:
    enabled: true
    requests_per_second: 100
    burst: 200
  query_log:
    enabled: true
    max_entries: 10000

Environment Variables

Environment variables take precedence over config file values. Set them in /etc/domudns/env:

Variable	Description
`DOMUDNS_SYNC_SECRET`	Required for cluster. 64-character hex string. Must be identical on all nodes.

bash
# Generate and set sync secret
openssl rand -hex 32 | sudo tee /etc/domudns/env
# Result: DOMUDNS_SYNC_SECRET=a3f2c8b1...

sudo chmod 600 /etc/domudns/env

Previous ← Quick Start Next REST API →