Guide
Choose how you manage settings
You can change WrenDNS from the web UI, a config file, Git, or the API. Pick the style that fits how you run it; they work together, and your config file is never rewritten.
Four ways to change a setting
Web UI
Upstreams, lists, groups, devices, local names, alerts, and more have a page with an editor. Check previews a change and warns you; nothing is saved until Apply.
Config file
wrendns.toml, plus more files if you like. Check it with wrendns config check, then apply it with a reload. Every key is in the configuration reference.
Git
Keep the file in a repository: Helm values with Argo CD or Flux, or a cluster that reads its shared settings straight from a repository.
API, CLI, and AI agents
Everything the UI changes, the API changes too (?dryRun=true previews). wrendns ctl wraps it for the shell, and AI agents propose plans that a person approves.
Pick a style
Most people use the first one. The others suit infrastructure that's managed as code.
Web UI on a config file (the default)
Good for: a Raspberry Pi or a home server you look after in the browser.
- The install's config file holds the basics: where to listen and which upstreams to ask. Leave it as it is.
- Add and change everything else on its page in the web UI: upstreams, lists, groups and schedules, devices, local names, quick rules, and alerts.
- Each change shows what it will do first. Changes are stored in
state.dbnext to users and the audit log, and they're included in backups.
Each editor's Manage table says where every entry comes from:
| Badge | Meaning |
|---|---|
| config file | Defined in your file. Edit makes an override; Remove hides it. |
| added here | Made in the UI or API. Remove deletes it. |
| overrides the file | The UI's version replaces the file's entry of the same name. Revert to the file brings the file's back. |
| hidden | The file's entry is left out. Revert to the file brings it back. |
Config file only
Good for: Ansible, Puppet, or a dotfiles repository, where every change is a reviewed diff.
- Edit
wrendns.toml. Split it if you like: later files override earlier ones (wrendns run -c base.toml -c site.toml). - Check it:
wrendns config check base.toml site.tomlreports every problem at once with its key path.--printshows the effective configuration. - Apply it without a restart:
systemctl reload wrendns, ordocker kill -s HUP wrendns. A file that doesn't validate is refused and the previous configuration keeps serving.
wrendns config check /etc/wrendns/wrendns.toml # "config OK", or every error with its path
sudo systemctl reload wrendns # applied with no dropped queries
Upstreams, groups, routes, local names, access, rate limits, special names, and listeners apply at once. [cache], [telemetry], and [node] wait for a restart (the log names them).
To keep the file the only source, give everyone else the viewer role: viewers see everything but change nothing.
Git, per node (Helm, Argo CD, Flux)
Good for: Kubernetes, where Argo CD or Flux applies the Helm values from your repository.
- Put your settings under
config:in the Helm values. The chart writes them after its own (listeners, data directory, ports). - Tell WrenDNS the file comes from Git, so the UI can help you keep the repository in step:
config: |
[cluster]
config_source = "gitops"
[[upstream]]
name = "quad9"
url = "tls://9.9.9.9"
tls_server_name = "dns.quad9.net"
Changes in the UI still work, at once. After Apply, the UI shows the TOML to add to your repository (under config:) with a Copy button. Once Git has it, Revert to the file removes the UI's copy, so the next rebuild from Git doesn't lose anything. The API returns the same text as keepInGit.
The Kubernetes guide covers the rest of the chart.
Git, for the whole cluster
Good for: "nothing changes unless it's in Git", across every node.
Option 1: the cluster reads one file from a repository. The primary fetches the shared settings, checks them, and hands them to every node, so every node serves the same commit:
# On every node that may become primary:
[cluster.git]
repo = "https://github.com/me/homelab"
ref = "main"
path = "wrendns/shared.toml"
# require_signed = true # only SSH-signed commits...
# allowed_signers_file = "/etc/wrendns/allowed_signers"
# webhook_secret_file = "/etc/wrendns/git-hook" # push webhook: applied in seconds
- A commit is used only if it validates and descends from the one in use; anything else is refused, and the cluster stays on the last good commit.
- If the repository is unreachable, every node keeps serving the last commit. DNS never waits for Git.
Option 2: only Git-managed nodes may publish. On the primary: wrendns cluster set-authority gitops (or wrendns cluster init --config-authority gitops), then restart. Only nodes with [cluster] config_source = "gitops" may publish the cluster's configuration. Any other node can only take over as an emergency primary, which keeps the last version until a Git-managed node is back. When one is back it takes the role again by itself after about a minute: with automatic failover it asks the emergency primary to hand over and is elected, with manual failover it promotes itself.
In both cases the UI and API stop changing shared settings: they answer 409 gitops_managed, and every change goes through your repository.
How the layers stack
From lowest to highest; a higher layer wins.
- Built-in defaults. Every key is optional.
- Config files, in the order given. Tables merge key by key; lists such as
[[listen]]replace the earlier one entirely. - Environment variables
WRENDNS_<SECTION>_<KEY>, such asWRENDNS_CACHE_MAX_TTL=3600. Handy in containers. - Command-line flags.
- The web UI and API, entry by entry: they add an upstream, list, or group, or override or hide one of the file's by name.
- In a cluster, the primary. Its shared settings replace the shared sections of every other node's own files.
wrendns config check wrendns.toml --print shows layers 1 to 4 merged. The UI's entries are listed with their source by GET /api/v1/config/entries.
Credentials are never shown. An upstream's headers and args, a password in any URL, an OIDC client_secret, and OTLP headers read <redacted> in the API, the audit log, the TOML to keep in Git, agents' plans, MCP, and --print (--show-secrets prints them on the node). Editing an entry keeps them while it points where it did; change its URL, proxy, TLS name, CA, bootstrap addresses, certificate checks (skip verify, pins) or an alert destination's type and the credential has to be typed again. Test it never uses a stored credential: type it into the draft. On a replica, keeping a credential this way needs a primary on the same version (until then, 409 upgrade_required).
Credentials: in the file, in a file, or stored
A router's API key, an alert destination's token, an OIDC client secret, a sink's token, OTLP headers, and the Git source's credentials can each come from one of three places, never two:
| Where | Config file | Good for |
|---|---|---|
| A file the node reads when it needs it | api_key_file = "/run/secrets/unifi" | Docker and Kubernetes Secrets, a key mounted read-only |
| A secret stored on the node, encrypted | api_key_ref = "unifi" | Entering it in the UI instead of on the machine |
| Inline (OIDC client secret and OTLP headers only) | client_secret = "..." | Trying something out |
A stored secret is write-only: nothing shows it again, admins included. It is encrypted in state.db with the node's own key (secrets.key in the data directory, made on the first start, or one you keep elsewhere with WRENDNS_SECRETS_KEY or [node] secrets_key_file; the Helm chart's secretsKey.existingSecret). A backup leaves them out unless you give it a passphrase (Settings → System → Backup, or wrendns backup create --secrets-passphrase-file): then they travel encrypted with a key made from it, and a restore stores them under the new node's own key. The node's key is never in a backup, and resolver pods hold neither.
wrendns ctl secrets set unifi --from-file /root/unifi-key # or: ... set unifi < key
wrendns ctl secrets list # names and users, never a value
wrendns ctl secrets clear unifi # refused while a field names it
Who sets one. Admins only (PUT /api/v1/secrets/<name> with {"value": "..."}), never an agent token (403 agent_not_allowed), and only over HTTPS or on the node itself: plain HTTP from another machine is 403 insecure_transport unless [api] allow_secrets_over_http = true (turn on [api] tls = { self_signed = true } instead). A TLS proxy in front, even one on the same host, must be listed in [api] trusted_proxies for this. Operators and agents with config:read see the names, who set them, and which fields use them (GET /api/v1/secrets, the MCP tool secrets_status). In a cluster the primary keeps them; a replica sends the change there. A secret a field still uses can't be deleted (409 secret_in_use).
Settings → Integrations & secrets. Operators and admins see this node's secrets store (its key's source and state), every stored secret with the fields that use it and the nodes that hold it, and every credential field with where its value comes from. Admins add, replace or delete a secret there. Every password or token field in the UI is a secret field: it shows that a secret is set, never the value, and clearing it stops the entry using it when you apply. Who may change a credential in a form. Only an admin changes where a credential is sent: an alert destination's address or type when it holds a token or password, an upstream's address or TLS server name when it keeps a header, a password or a credential file, and an address that runs a program (exec://, unix://). An operator sees those fields read-only, with the reason. A kept value is never shown again: its entry says kept: re-enter to change, and a change that would send it somewhere new is refused with the field's name. The help topic "Who may change a credential" says more.
The files win. A credential the config file sets can't be changed in the UI (409 set_by_file). If the key is missing or wrong, the store is locked: integrations that use a stored secret say "not configured", health is degraded (secrets_locked), and DNS keeps answering. wrendns secrets status shows what the node can read; wrendns secrets rotate-key replaces the key. Custody, rotation and recovery: docs/secrets.md.
Guarded settings: the ones that can lock you out
A few settings can lock every admin out, put passwords on the wire, re-encrypt your stored secrets, or replace a node's configuration: the listeners, the API's address, certificate and trusted proxies, the secrets key, allow_secrets_over_http and allow_insecure_basic, the watchdog, the file paths the server reads, a node's name and data directory, and the cluster actions. In the web UI they go through one safe process. Admins only: AI agents and API tokens can't change them, and operators and viewers don't see the controls.
- Review. The page says what the change does, which node it reaches, and what could go wrong, marks a change that weakens security in red, and shows a phrase such as
pi-a listen(in a cluster the node is named by its ID, and a node picker chooses the node). Nothing has changed yet. - Type the phrase. The server checks it, so a script can't skip it. A change that weakens security also asks for your password again (a sign-in from the last 10 minutes).
- Confirm through the new address. A change to an address, certificate or proxy list is applied next to the old one and kept only if you open the new address and press Confirm within the window (120 seconds by default). If you can't reach it, do nothing: it rolls back by itself and says why.
A change that needs a restart is shown as pending restart. The Restart now button is offered only where the install declares something that will start the node again (the shipped systemd unit, Compose bundles and Helm chart do); otherwise the page shows the manual steps. If a staged change keeps the node from starting healthy, two starts later it is dropped and the node starts from its file.
A file always wins over what you set here, and the control says "set by file". If you do get locked out, no recovery needs the UI: set the value in the config file and restart, run wrendns guarded list and wrendns guarded clear with the node stopped, or start it once with WRENDNS_IGNORE_GUARDED=1. Every change and rollback is in the audit log, and the guarded_setting_changed alert tells a second channel. See docs/recovery.md for the symptom-by-symptom table.
Where each setting lives
The same setting, three ways. API paths take PUT to save, DELETE to remove, and ?dryRun=true to preview.
| Setting | Web UI | Config file | API |
|---|---|---|---|
| Upstream servers and groups | Upstreams | [[upstream]], [[upstream_group]] | /api/v1/upstreams/{name}, /api/v1/upstream-groups/{name} |
| Blocklists | Lists | [[list]] | /api/v1/lists/{name} |
| Groups | Groups | [[group]] | /api/v1/groups/{name} |
| Schedules | Groups → Schedules | [[schedule]] | /api/v1/schedules/{name} |
| Devices | Click any address → Name this device… | [[client]] | /api/v1/clients/{name} |
| Local names | Names on your network | [[record]], [[zone]] | /api/v1/records/{name} |
| A domain sent to another server | Names on your network → Send a domain to another server | [[route]] | /api/v1/forwards/{domain} |
| Quick block and allow rules | Quick rules | [[rule]] | /api/v1/rules/{id} |
| Rate limit | Settings → Query handling | [ratelimit] | /api/v1/ratelimit/default |
| Kept out of the log | Settings → Query handling | [exclusions] | /api/v1/exclusions/default |
| Change simulation | Settings → Query handling | [simulate] | /api/v1/simulate-settings/default |
| Special names (iCloud Private Relay, one-label names, DDR) | Settings → Query handling (the DDR name is an admin's) | [special] | /api/v1/special-names/default |
| Device names in DNS | Local DNS → Device names in DNS | [local] | /api/v1/local-settings/default |
| Listening for mDNS announcements (an admin's) | Local DNS → Listen for mDNS announcements | [clients] mdns | /api/v1/clients-settings/default |
| Network map (sampling and thresholds) | Settings → Query handling → Network map | [map] | /api/v1/map-settings/default |
| Alerts | Alerts | [[alerts.destination]], [[alerts.rule]] | /api/v1/alerts/destinations/{name}, /api/v1/alerts/rules/{name} |
| Staged rollouts | Settings → Cluster | [cluster.rollout] | /api/v1/cluster/rollout-settings/default |
| Listeners, the API, sign-in, telemetry, cache, the node | (config file only) | [[listen]], [api], [auth], [telemetry], [cache], [node] | (config file only) |
Every change through the UI or API is checked first, refused if it would leave the configuration invalid, and recorded in the audit log with who made it. The full API is described at /api/v1/openapi.json on every node.
The cache, list limits, DNSSEC and the small switches
Most of these are a form on the page they belong to, with a check before the change is saved:
- Cache (the Cache page): memory, how long answers are kept, stale answers, prefetch and the warm start for each node. Operators change them; each node applies its own, when it restarts.
- Lists: a largest download and a stale age for each list, and the refresh interval for all of them (after a restart).
- DNSSEC (Query handling): the validation mode and the domains not validated.
- Drills (the Cluster page): whether the failover drills run each month, and on which nodes.
- System: this node's support-log and update-check switches (admins).
Each control has a ? beside it that explains what the setting does, and the API has the same change: see the reference on the developers' pages.