Configure DNS Deny.

Saved state and restarts

Start with the complete general-purpose seed or the Pi Zero seed. This reference follows the current source and those examples. “Seed value” means the general-purpose example, including defaults applied to omitted optional fields; it is not a promise to overwrite an existing installation.

1. First start: open DNS_STATE_DB. If no configuration row exists, read DNS_CONFIG, normalize the optional API token, validate, and persist revision 1.
2. Later starts: load and validate the saved database configuration. Do not merge new seed values into it. Invalid or unsupported state fails startup; it is not silently replaced by a fresh seed.
3. Supported updates: dashboard actions and dedicated API endpoints validate a candidate, commit it to SQLite, then publish a new in-memory configuration. Failed validation or persistence leaves the live configuration unchanged. Rule files and downloaded source caches have their own persistence; they are not all inside state.db.
4. Requests in flight: an existing DNS request may finish using its earlier configuration snapshot. New requests read the published settings. Downstream clients may still retain DNS answers until their own cache expires.

GET /api/v1/config is read-only and redacts credentials. A settings response can show a saved value before a startup component has been rebuilt. Do not interpret “saved” as “already active” for restart-required settings.

Settings endpoints below use POST unless another method is named, and require JSON API authentication. Send the complete object expected by that settings section, not an arbitrary fragment of the full configuration. For example, service updates replace both blocked_services and custom_services; blocklist updates replace both source arrays. Use the dashboard if you do not need to automate those updates.

Environment and paths

These are process environment variables, not command-line flags. Relative paths resolve from the process working directory.

The packaged service uses /var/lib/dns-deny as its working directory, with the seed at /etc/dns-deny/config.toml. Docker also stores data under /var/lib/dns-deny, with dashboard assets under /usr/share/dns-deny/static. Keep the data directory private and writable by the service user; the seed may stay read-only.

DNS_CONFIG=/absolute/path/to/private-config.toml \
DNS_STATE_DB=/absolute/path/to/dev-state.db \
DNS_PORT=1053 \
  ./target/release/dns-deny

Prepare the complete seed and replace its sample password before using this example. Changing DNS_CONFIG while keeping an existing DNS_STATE_DB will still use the saved configuration.

Network access

DNS admission controls apply before device policies, caches, filtering, logging, or upstream queries.

bind_address = "0.0.0.0"
allowed_client_cidrs = ["127.0.0.0/8", "192.168.1.0/24", "::1/128"]

Upstreams, encryption, and DNSSEC

The primary forwarding pool, the custom DoH client, and the threat-discovery pool serve different purposes. A blocklist URL is not an upstream resolver.

[[upstreams]]
address = "1.1.1.1"
protocol = "dot"
tls_sni = "cloudflare-dns.com"

Use the same upstream object shape for auto_block_upstreams. Configure its TLS names explicitly too.

Blocklists and source updates

Downloaded list subscriptions and local allow/deny rules are restored before the DNS listener opens. A background refresh then checks remote sources; an offline restart can use the last successful downloads.

Formats, failure handling, and persistence

Imports recognize plain domains, hosts files, unconditional domain-style Adblock entries, regex lists, and Pi-hole Gravity databases. Contextual browser rules such as resource-type, third-party, or domain-scoped exceptions are skipped because DNS cannot supply that context.

Conditional HTTP requests reuse validators from successful imports. Failed downloads, oversized inputs, or failed rebuilds retain the last working rules rather than publishing an empty filter. Source status is visible in list management; POST /api/v1/lists/sources/sync requests a network refresh. A local allow/deny edit rebuilds from already available source rules without downloading every list.

Limits are 32 MiB and one million rules per source, 16 KiB per line/pattern, and two million retained source rules / 64 MiB of retained pattern text in aggregate. These are import limits, not total process-memory limits. Valid large regex sets are partitioned into at most eight compiled sets; a failed rebuild preserves the previous snapshot.

[[blocklist_categories]]
id = "ads"
name = "Advertising"
urls = ["https://adaway.org/hosts.txt"]
enabled = true

Manage local domains and regexes through list management. They live in separate rule files, not a local_denies TOML setting. Domain entries include subdomains; explicit domain allows precede denies across filter tiers. Service blocks still take precedence over domain allows.

Threat discovery and scoring

Discovery asks a separate filtering resolver whether a public name is sinkholed. It is distinct from the resolver that obtains the primary DNS answer.

Discovered auto-denies are persisted in auto_blocked.txt and restored after restart. Disabling discovery does not delete previously learned denies; remove a false positive explicitly. New auto-deny persistence stops at 100,000 entries, while live threat and malicious-IP checks continue. Review inherited malicious_ips.txt entries when upgrading from older behavior.

Devices and schedules

Device rules apply to the client identity visible to this server. MAC identity is available on the local network segment; NAT and routed clients may need IP policies.

Linux ARP and IPv6 NDP discovery refreshes every five seconds and discards stale identities. While a MAC block or a blocking MAC schedule is active, an unidentified client receives REFUSED until identified. A MAC whitelist does not grant bypass before identification. Device discovery and counters are in memory and rebuild after restart; saved policies and aliases remain.

[device_policies]
"aa:bb:cc:dd:ee:01" = "block"

[[device_schedules]]
ip = "192.168.1.25"
policy = "block"
days = ["mon", "tue", "wed", "thu", "fri"]
start_time = "21:00"
end_time = "07:00"

[[client_aliases]]
identifier = "192.168.1.25"
name = "Study laptop"

Services, SafeSearch, and local DNS

Service and domain policy runs before DNS rewriting or local answers. Configured local owners stay local; explicitly external CNAME targets are resolved separately.

A locally known name queried for an unconfigured type returns empty NOERROR (NODATA), not upstream NXDOMAIN. Local CNAME chains are followed with a hop bound; loops/excessive chains fail rather than resolving indefinitely. Changing a local record publishes a fresh local index; client-side cached answers can outlive that edit.

[[local_dns_records]]
name = "nas.home.arpa"
record_type = "A"
value = "192.168.1.100"

[[custom_services]]
id = "games"
name = "Example games"
description = "Block the example gaming domain"
wildcards = ["games.example.com"]
enabled = true

Protection pauses

Pauses are saved expiry timestamps, not durations restarted at boot. A future expiry remains active after restart; time spent stopped still counts. Expired timers are ignored immediately on requests and cleaned up by housekeeping.

{"scope":"device","id":"aa:bb:cc:dd:ee:01","duration_secs":3600}

Send that JSON body to POST /api/v1/protection/pause. To resume early, send the same scope and id to POST /api/v1/protection/resume. Other scopes are global, category, and service; global needs no ID. An already-active pause for the same normalized identity returns HTTP 409. Query GET /api/v1/protection/status for active timers.

Caches and DNS rate limits

Both DNS cache tiers are in memory and start cold after every process restart. Capacity settings are captured at startup; there is no general cache-capacity or DNS-rate editor.

Positive DNS answers age using their record TTLs. Negative answers use the SOA rule above. Transport failures and SERVFAIL are transient and are not stored as successful answers. Policy checks also examine cached CNAME chains and address answers so a cache hit does not bypass new filtering rules.

To clear server response and verdict caches without restarting, use the dashboard cache tool or POST /api/v1/cache/invalidate. This cannot clear clients’ or upstream providers’ caches. Cache clearing does not delete configuration, rule files, or logs.

Query logs and retention

DNS query history uses a separate SQLite file from persistent configuration. Restarting keeps committed history. Queued or unflushed records are not durable and can be lost during a crash, shutdown, or restart.

Log writes are batched, normally flushed at most every 200 ms or after 500 entries, with SQLite work kept off the DNS runtime. Historical statistics use retained rollups; they are not a copy of state.db. Back up live SQLite logs with an SQLite-aware backup or after stopping the service, rather than copying only the main file while its WAL is changing.

Administration and credentials

The default build serves the dashboard and JSON API. Dashboard-only builds still need the HTTP admin server; resolver-only builds omit it and should set api_enabled to false.

Sessions versus API tokens

The dashboard uses a 12-hour HttpOnly, SameSite=Strict session cookie. Sessions are in memory: restart or logout invalidates them, even though the administrator password remains saved. Cookie-authenticated changes require the matching Origin and public Host.

JSON API requests use Authorization: Bearer <credential>. Until a dedicated token exists, the administrator credential is accepted. Issue one with POST /api/v1/auth/token; it is returned once and only the digest is saved. DELETE /api/v1/auth/token revokes it and returns API authentication to the administrator credential. A password change does not revoke a dedicated token.

Updates, backups, and troubleshooting

Keep application upgrades separate from configuration changes. Replacing a binary or container should retain the existing data and should not re-seed your installation.

What survives restart?

Upgrade an existing installation

1. Review the release’s configuration/state compatibility and record any restart-required settings you have saved.
2. Stop the service for a simple consistent backup, or use SQLite-aware backups for live databases. Save state.db, rule files, cached sources, and query history if needed, along with the seed and service environment. Keep credentials and backups private.
3. Replace the binary and matching dashboard assets, or rebuild/recreate the container while retaining its named data volume. Do not use volume deletion as an upgrade step.
4. Start the service and check startup diagnostics, DNS queries, source status, and admin sign-in. The new release reads saved state; a newly shipped seed does not overwrite it. Newly introduced optional fields may receive their code defaults when absent from older saved state.

For startup fields without an editor, plan a stopped-service state migration or an intentional new installation with a reviewed complete seed. There is no supported general-purpose SQL editing workflow. Pointing DNS_STATE_DB at an empty path starts a separate state; deleting the old database loses its settings and credentials and is not a routine update or password-reset procedure.

Manual changes to rule files are not a supported hot-reload interface. Use dashboard/API list management while the service is running; preserve the files when restarting or replacing the application.

Common surprises

I changed TOML, but nothing changed.

The existing database is authoritative. Use the relevant settings editor or endpoint. Changing DNS_CONFIG does not override existing state.

The settings page shows new upstreams, but traffic uses the old servers.

The new pool is saved for restart. Restart the process and let client-side caches expire.

I changed custom DoH, but a cached name still shows the earlier result.

The DoH client updates live; existing server/client caches can retain answers. Use the server cache tool if appropriate and account for client TTLs.

I paused a category or service, but its domain is still blocked.

A base list, another category, service, local deny, or malicious-IP rule can still match. Pauses only remove their own protection scope.

Primary DNS works, but protected lookups receive SERVFAIL.

If sinkhole discovery is enabled, check the threat resolver and discovery budget too. Also inspect local DNSSEC failures; an upstream answer alone does not prove validation.

A different device inherited an address and cannot use an old whitelist.

MAC policies intentionally avoid transferring bypass across DHCP changes. Check neighbor visibility and resave an ambiguous legacy policy; do not grant a broad IP bypass to work around identification.

The service restarts, but I cannot stay signed in.

Browser sessions are process-local. Sign in again; the saved password and dedicated API token remain valid unless explicitly changed.

Examples are fragments

Use the complete shipped seed as the starting file. Examples above describe selected fields; do not concatenate them blindly. In TOML, root scalar settings must appear before [table] or [[array_of_tables]] sections. Merge keys into their correct tables and do not define the same key twice.

Source references: configuration model and validation, startup loading, settings endpoints, and repository configuration guide. Use the documentation and code matching the version you deploy.