Warda-DNSDocs
EN
Menu

Configuration

Every setting is a flag of warda serve or an environment variable.

Variable Default Meaning
WARDA_DNS_LISTEN :53 DNS address (UDP and TCP)
WARDA_HTTP_LISTEN :80 Plain HTTP address: redirect to HTTPS, /healthz, /api/v1/stats
WARDA_UPSTREAMS Quad9 and Cloudflare (DoT, DoH, plain) Upstreams, tried in order
WARDA_LISTS base.txt of warda-lists Blocklist URLs or file paths
WARDA_LIST_REFRESH 1h Blocklist refresh interval (minimum 1m)
WARDA_CATEGORY_LISTS warda-lists category=url|url list sources of the sensitive categories (security, adult, violence, hate, drugs, gambling, piracy, social, video, games, jobsearch, bypass, newdomains, csam)
WARDA_DATA_DIR /var/lib/warda Persistent data
WARDA_ALLOW Domains (or /regular expressions/, without a comma) never blocked
WARDA_BLOCK Domains (or /regular expressions/, without a comma) always blocked
WARDA_FORWARD zone=upstream rules for local zones
WARDA_ALLOWED_CLIENTS private ranges CIDR ranges allowed to query; with the default, the global IPv6 networks and the shared (CGNAT) networks of the machine's interfaces (host networking) are added, followed as they change
WARDA_CACHE_SIZE 10000 Cached responses
WARDA_BLOCKED_TTL 10 TTL of blocked answers, in seconds
WARDA_HTTPS_LISTEN :443 Web interface and administration API (empty to disable)
WARDA_ADVERTISE_ADDR found on the interfaces IPv4 address(es) answered for warda, warda.lan, warda.home.arpa
WARDA_PASSWORD_BREACH_CHECK true Refuse passwords found in known breaches
WARDA_LEARN_LEVEL medium off, low, medium or high
WARDA_LEARN_WARMUP 168h Observation period after installation
WARDA_DEVICE_WARMUP 48h Observation period of a new device
WARDA_SUGGESTIONS_PER_WEEK 10 Maximum new suggestions over 7 days
WARDA_OWN_DOMAINS Your own domains, never suggested
WARDA_JOURNAL_DAYS 30 Days of query journal kept
WARDA_JOURNAL_MAX_MB 2048 Maximum size of the database, in MiB
WARDA_LOG_LEVEL info debug, info, warn or error
WARDA_LOG_FORMAT text text or json
WARDA_DOT_LISTEN :853 DNS over TLS for the devices, when turned on in the interface
WARDA_DOQ_LISTEN :853 DNS over QUIC (UDP) for the devices, when turned on in the interface
WARDA_CLOUD_URL https://cloud.warda-dns.com Online service of Warda (the name and certificate given by Warda, the anonymous daily statistics; empty: never sent)
WARDA_ACME_DIRECTORY Let's Encrypt Certificate authority (ACME) of the encrypted DNS

Lists are comma-separated. Upstreams are written as:

text
udp://9.9.9.9:53
tcp://9.9.9.9:53
tls://9.9.9.9:853#dns.quad9.net           (after # : TLS server name)
https://dns.quad9.net/dns-query#9.9.9.9   (after # : server IP address)

Upstreams are always reached by IP address: Warda is the resolver of the network, so it must not depend on DNS to find its own upstreams.

The default WARDA_ALLOWED_CLIENTS are 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, ::1/128, fc00::/7 and fe80::/10. With them, Warda also allows the global IPv6 networks of the interfaces of the machine, and the shared networks (CGNAT, inside 100.64.0.0/10) it is attached to. The interfaces are read again every minute, and 5 seconds after a client was refused, so that a new prefix of the internet box is accepted without a restart. 100.64.0.0/10 is not allowed as a whole: it also holds the other customers of a carrier-grade NAT. It is when the machine holds a single address of it (/32), as with Tailscale or Headscale, whose peers take their addresses in the whole range. An explicit list is used as is. Queries from other addresses get no answer (DNS over QUIC drops them before the handshake).

How the DNS server answers:

  • Over UDP, an answer leaves from the address the query was sent to (a second address or a virtual IP of the machine).
  • Above 2048 queries in progress at once, all protocols together, the extra ones get SERVFAIL at once (counted as dropped in /api/v1/stats).
  • Zone transfers and meta types (AXFR, IXFR, MAILA, MAILB, OPT) are answered NOTIMP by Warda itself. resolver.arpa and _dns.resolver.arpa (discovery of designated resolvers, RFC 9462) get an empty answer (NODATA), the other names under resolver.arpa NXDOMAIN: Warda publishes no designation.
  • An upstream that answers REFUSED, NOTIMP or FORMERR is working: the next one is asked for that query, and it is not shown as down.
  • The first upstream tried gets at least 1.5 seconds (within the time left) before the next one is asked, however many upstreams are configured.

Example of conditional forwarding to a router:

sh
WARDA_FORWARD="home.example=udp://192.168.1.1:53,168.192.in-addr.arpa=udp://192.168.1.1:53"

Blocklists may use plain domains, hosts files, *.domain wildcards or the DNS subset of Adblock syntax (||domain^, @@||domain^). Every entry blocks the domain and its subdomains. Rules Warda cannot apply exactly are ignored.