nxdns/docs/reference/cli.md

CLI reference

nxdns <command> [options]

nxdns has six commands: run, check, export, import, version and help.

Flags take their value either way, --data-dir /srv/nxdns or --data-dir=/srv/nxdns. A command rejects a flag it has no use for.

run

Serves DNS and the web interface until it receives SIGINT or SIGTERM.

Flag	Meaning
--data-dir DIR	The data directory, /var/lib/nxdns by default. Created at mode 0700 if missing.
--config FILE	Run in file mode, with FILE as the configuration.
--admin-dev DIR	Serve the web interface from DIR instead of the copy built into the binary. For developing the interface.

Without --config, nxdns runs in database mode: the configuration is what config.db holds, and you change it in the web interface. With --config FILE, the file is the configuration: every start makes the database match it, and the web interface shows the configuration read-only. A file at /etc/nxdns/config.zon that no --config names is not read. The configuration model compares the two.

The log names the mode at every start:

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

In file mode it first says what the file changed: entries added (+), changed (~) and removed (-) per list, and the settings that changed.

reconciled '/etc/nxdns/config.zon': upstreams +1 ~0 -0; settings +46 ~0 -0;
settings keys changed: dns.bind_ipv4 dns.port web.bind web.port …
web authentication is now enabled

A start whose file changed nothing says so:

reconciled '/etc/nxdns/config.zon': no changes

A blocklist whose URL the file still names keeps its download across restarts. Changing a list's URL makes it a new list, downloaded afresh.

In file mode, a file that is missing, unreadable or invalid stops the start with exit 2. nxdns never falls back to the database, which would leave you running a configuration you did not deploy:

FAIL /etc/nxdns/config.zon: no such file
nxdns run failed: ManagedConfigUnreadable
run `nxdns check` to see the configuration in full

check

Checks a configuration and tests the upstreams, then exits 0 if nothing failed and 2 if something did. It reports every problem, not just the first.

Flag	Meaning
--data-dir DIR	The data directory whose config.db to check.
--config FILE	Check FILE instead of the database.

Like run, it checks the file when you name one and the database when you do not, so nxdns check --config FILE checks exactly what nxdns run --config FILE would serve. Run it before you restart nxdns on a changed file.

It checks, in order:

1. That the file or database can be read, and the file's syntax.
2. Every rule in the configuration reference.
3. For each DoH or DoT listener that is on, that the certificate and key load and belong together. A key that others can read is a warning.
4. One real query for example.com through each enabled upstream, within the configured timeouts. This needs network access.

checking configuration file /etc/nxdns/config.zon
OK upstreams[0] https://cloudflare-dns.com
OK: no problems found

Each problem is a FAIL or a WARN line. A WARN marks something allowed but probably unintended, such as a blocklist no group uses, and does not change the exit code. The last line sums up:

Found	Last line	Exit
Nothing	OK: no problems found	0
Warnings only	OK: no failures found, 2 warnings	0
A failure	the FAIL lines, with no summary	2

With no --config and no database yet, check says how to get one:

no config database at /var/lib/nxdns/config.db
load one with `nxdns import <file>`, or make a file the source of truth with `nxdns run --config <file>`

check never changes the database. Two of its findings are therefore not damage:

• FAIL <db>: schema version <n>, this nxdns expects <m>; …: the database is from an older release. Starting nxdns upgrades it.
• FAIL <db>: uncheckpointed changes are waiting in <db>-wal, …: recent changes from a running nxdns are not in the main file yet. Check an export with --config instead, or stop nxdns first.

export

Writes the configuration to standard output as ZON, or to a file with --out.

Flag	Meaning
--data-dir DIR	The data directory holding config.db.
--out FILE	Write to FILE, created at mode 0600, instead of standard output.

The output lists every setting, defaults included, in a fixed order with no timestamps, so exporting the same configuration twice gives the same bytes. It works while nxdns is running.

The password is written as .password = null with its hash in .password_hash, so the export restores the same password without revealing it. See Back up and restore.

import FILE

Makes the database match FILE, all at once or not at all. If FILE has any problem, import reports every one and changes nothing. It creates the data directory at mode 0700 if it is missing.

Flag	Meaning
--data-dir DIR	The data directory holding config.db.
--allow-delete	Apply a file that removes entries the database holds.

Stop nxdns before you import: a running server would pick up only part of the change.

Removing entries

Entries the database holds and FILE does not name are removed. That is how a restore undoes later changes, and also how importing the wrong file would empty a configured server, so import refuses until you add --allow-delete:

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 says how many entries of each kind would go. Nothing is changed, and the exit code is 2.

Adding entries or changing them needs no flag. An entry is recognised by these fields, and changing one of them removes the old entry and adds a new one:

List	Recognised by
upstreams, blocklist_sources	url
groups	name
clients	ip
client_prefixes	prefix
forward_zones	zone
local_records	name, rtype and value
rules	group, pattern, kind and action

Renaming a group or correcting an upstream's URL therefore needs --allow-delete; changing a client's group or a list's name does not.

What an import keeps

A blocklist whose URL is unchanged keeps its download. Devices nxdns discovered keep their history, and a device the file names keeps its first-seen and last-seen times. A discovered device whose group the file removes moves to default.

version

Prints the nxdns version, then the Zig version it was built with.

nxdns <version>
zig 0.16.0

help

Prints the usage text and exits 0. nxdns --help and nxdns -h do the same.

Exit codes

Code	Meaning
0	Success.
1	A failure a retry might clear: a disk, network or database error, or running out of memory.
2	Something only you can fix: a configuration problem, a check that found one, a --config file that is missing or unreadable, an import that would remove entries, or a database nxdns refuses to open.
64	A wrong command line: an unknown command or flag, or a missing or extra argument.

The packaged systemd unit restarts nxdns after exit 1 and not after exit 2 or 64, since restarting would only repeat the error. When run exits 2 it says what to do next:

run `nxdns check` to see the configuration in full

run also exits 2 when it refuses the query history database, querylog.db, rather than risk it. The message names the file and what to do. A database from a newer release, after you went back to an older one, is the usual case; see Going back to an older release.