nxdns/docs/explanation/configuration-model.md

The configuration model

You can configure nxdns in its web interface or in a ZON file, but only one of them is the configuration at a time. This page explains how nxdns decides which, what each mode suits, and what nxdns keeps whichever you choose.

The settings themselves are in the configuration reference, and the commands in the CLI reference.

The command line decides

nxdns run                                   database mode: the web interface is the configuration
nxdns run --config /etc/nxdns/config.zon    file mode: the file is the configuration

Nothing else decides: there is no mode setting and no default file path. A config.zon that no --config names is never read. You can always tell which mode a server runs in from its command line, its systemd unit or its compose file, and the log says so at every start:

info(nxdns): authority: database
info(nxdns): authority: file (/etc/nxdns/config.zon)

Database mode

nxdns keeps the configuration in config.db, and you change it in the web interface. Changes apply as you save them; the few that need a restart, such as a listening port, are marked needs restart.

This suits a box someone sets up once, after which anyone in the household can unblock a domain without touching a file.

A new database is empty, and an empty configuration has no upstream to send queries to, so the first start needs a configuration loaded with nxdns import:

nxdns run failed: NoUsableUpstreams
run `nxdns check` to see the configuration in full
load one with `nxdns import <file>`, or make a file the source of truth with `nxdns run --config <file>`

File mode

The file is the configuration. Every start reads it, checks it and makes the database match it. The web interface still shows everything nxdns does, but its configuration pages are read-only and name the file to edit instead.

This suits a file kept in git and deployed by a tool such as Ansible or NixOS: what is deployed is what runs, and nobody can change it from a browser behind the tool's back.

• A bad file stops the start. A missing, unreadable or invalid file makes nxdns exit with code 2, rather than run on whatever the database held before. Run nxdns check --config FILE in your deploy before the restart, so a typo fails the deploy instead of stopping DNS.
• An unchanged file changes nothing. The start logs reconciled '…': no changes, and writes nothing to disk.
• The file is the backup. Losing the data directory loses only the query history and the list of devices seen; the next start rebuilds the configuration from the file and downloads the blocklists again.

What nxdns keeps in either mode

Some things are not configuration, and making the database match a file never removes them:

• Blocklist downloads. A list whose URL is unchanged keeps its download, so a restart downloads nothing. A list whose URL changed is a new list, downloaded afresh.
• Devices nxdns has seen. Their first-seen and last-seen times stay, also when you give one a name in the file. When the file removes a group, its devices move to default instead of disappearing.
• The password, when the file does not mention it. See Passwords.

Moving between the file and the web interface

nxdns export writes the database as a file that nxdns import and file mode both read. That makes the file useful in database mode too: export it to keep a readable, diffable copy, or edit it and import it back.

nxdns export  →  ZON file  →  edit  →  nxdns import  →  config.db

An export lists every setting, defaults included, in a fixed order, with no timestamps. Exporting the same configuration twice gives the same bytes, so a diff between two exports shows only real changes. Importing an export and exporting again gives the same file back.

To switch a database-mode server to file mode, export its configuration and start it with --config on that file; the first start changes nothing. To switch back, drop --config: the database already holds the last configuration the file set. Install with systemd has the commands.

Unknown settings

A setting nxdns does not know is an error in a file and a warning in the database.

In a file, an unknown name is most likely a typo, and ignoring it would leave you believing a setting applies when it does not. So the file is refused, with the line and column.

In the database, an unknown setting almost always means an older nxdns is reading a database a newer one wrote, after you went back a release. Refusing to start would make going back impossible, so nxdns warns, ignores the setting, and picks it up again once you upgrade.

What is not in the file

The data directory and the configuration file's own path are command-line arguments, --data-dir and --config, because nxdns needs them to find everything else. They belong to whatever starts nxdns: the systemd unit, the compose file or the NixOS module. Files and directories lists what lives where.