Back up and restore

The configuration is the only state worth backing up. The query history is not part of a backup, and the blocklists download again on their own.

What the backup is depends on the mode nxdns runs in. The start log says which:

authority: database: the configuration lives in config.db. Back it up with nxdns export and restore it with nxdns import. The rest of this page is about this mode.
authority: file (<path>): the configuration is that file, and the file is the backup. To restore, put the file back and start nxdns; it rebuilds its database from the file.

The commands below use the default data directory, /var/lib/nxdns. Add --data-dir DIR if yours is elsewhere.

Back up

nxdns export --out /var/backups/nxdns-config.zon

wrote /var/backups/nxdns-config.zon

This works while nxdns is running. The file is written in one step, so an interrupted export leaves no half-written backup, and it is created at mode 0600 because it carries the admin password's hash:

        .password = null,
        .password_hash = "$argon2id$v=19$m=19456,t=2,p=1$…",

The plaintext password is never stored, so .password is always null, and the file restores the same password without anyone knowing it. Keep backups as private as the database.

Without --out, the export goes to standard output.

An export holds configuration only: settings, groups, upstreams, devices you named, blocklist sources, rules and local records. It leaves out what the server records while it runs, such as when a device was last seen or how many domains a list held, so two exports of the same configuration are identical.

Restore onto a new machine

On an empty data directory, import loads the backup:

nxdns import /var/backups/nxdns-config.zon

info(migrations): config.db migrated from schema version 0 to 1
imported /var/backups/nxdns-config.zon

Under systemd, run it as root and then chown -R nxdns:nxdns /var/lib/nxdns before you start the service. Under Docker, see Database mode instead.

Restore over an existing configuration

Stop nxdns first. A running server read its configuration when it started, and would only pick up part of the change.

systemctl stop nxdns
nxdns import /var/backups/nxdns-config.zon
systemctl start nxdns

import makes the database match the file. Entries the file names are added or updated. Entries it does not name would be deleted, which is what restoring an old backup does to everything added since, so import refuses until you confirm, and changes nothing:

FAIL import: this file would delete rows the database holds (upstreams 1); re-run with --allow-delete to apply it
import failed: DestructiveImport

The message names what would go. If that is what you want, run it again with --allow-delete:

nxdns import /var/backups/nxdns-config.zon --allow-delete

Renaming a group or changing an upstream's URL counts as a deletion too: the old entry goes and a new one arrives.

A restore keeps what does not belong in a backup. A blocklist whose URL is still in the file keeps its download, so nothing is fetched again. Devices nxdns discovered on the network keep their history, and a device the backup names keeps the first-seen and last-seen times the database already had. A device you named by hand that the backup does not name is deleted with the rest.

Check a backup

Exporting the same configuration twice gives the same bytes, so a backup that loads and exports back unchanged is complete. To check one without touching the real data directory, load it into a scratch directory and compare:

nxdns import /var/backups/nxdns-config.zon --data-dir /tmp/nxdns-check
nxdns export --data-dir /tmp/nxdns-check --out /tmp/nxdns-check.zon
diff /var/backups/nxdns-config.zon /tmp/nxdns-check.zon && echo "backup is complete"

What a backup leaves out

querylog.db, the query history. nxdns creates an empty one when it is missing. To keep the history as well, copy querylog.db while nxdns is stopped.
blocklists/, the downloaded lists. They come back from the sources the configuration names.

Files and directories lists everything in the data directory.

4.2 KiB Raw Blame History