Files and directories

Every file nxdns reads or writes, and who may read it.

The data directory

/var/lib/nxdns by default, or the directory --data-dir names. nxdns run and nxdns import create it at mode 0700 when it is missing.

Path	What it is	Mode
`config.db`	The configuration, including the password hash. In database mode this is the configuration; in file mode nxdns rebuilds it from the file at every start.	0600
`querylog.db`	The query history: every name every device asked for. See The query history database.	0600
`config.db-wal`, `config.db-shm`, `querylog.db-wal`, `querylog.db-shm`	SQLite’s working files for each database. They hold the same data, and belong with their database whenever you copy or move it.	0600
`querylog.db.pre-migrate-<unix-seconds>`	A copy of the query history taken just before an upgrade converted it. The latest one is kept.	0600
`querylog.db.<reason>-<unix-seconds>`	A damaged query history, moved aside; see below.	as it was
`blocklists/`	The downloaded blocklists, compiled.	0700
`blocklists/<id>.list`, `<id>.wild`, `<id>.allow`	One blocklist’s domains, wildcard entries and exceptions. `<id>` is the list’s number in nxdns.	0600
`blocklists/<id>.*.tmp`	A download in progress.	0600

The databases are private because they are sensitive: config.db holds the password hash, and querylog.db and its copies hold the browsing history of every device on your network. nxdns restricts them to 0600 whatever the umask.

nxdns deletes a blocklist’s files when you remove the list, and at startup it deletes any left behind by a list removed while it was down or by a download that was interrupted:

info(blocklist_manager): pruned orphaned blocklist file 9999.list

nxdns check only reads the data directory, and changes nothing in it.

The query history database

At each start nxdns checks querylog.db before it serves anything.

Current: it opens.
From an older release: nxdns copies it to querylog.db.pre-migrate-<unix-seconds>, then converts it in one step. If converting fails, the file keeps its old contents and nxdns refuses to start.
Missing: nxdns creates an empty one.
Damaged: nxdns renames it to querylog.db.<reason>-<unix-seconds>, deletes its -wal and -shm files, and starts an empty one. <reason> is corrupt, not-a-database or quick-check-failed. Nothing deletes these copies; remove them when you no longer want the history in them.

Written by a newer release, or too old to convert: nxdns refuses to start, exits 2 and leaves the file as it is. The message says what to do:

refusing to open querylog database '/var/lib/nxdns/querylog.db': it is stamped 2, and this build supports schema versions 1 to 1 (SchemaTooNew). The file is left exactly as it is; a newer nxdns wrote it. Run that release again, put back the querylog.db.pre-migrate-* copy an upgrade left beside it, or move the file aside, together with its -wal and -shm files, to start with an empty query history

To start with an empty history, stop nxdns and move the three files aside:

cd /var/lib/nxdns
mkdir -p old-querylog
mv querylog.db querylog.db-wal querylog.db-shm old-querylog/

mv complains about a -wal or -shm file that is not there; that is fine.

A healthy query history is never replaced or deleted. A release that cannot convert the old history says resets your query history in its release notes, and explains how to keep the old file.

Going back to 0.0.13 or older

Releases up to 0.0.13 do not recognise the current query history. They rename it to querylog.db.schema-changed-<unix-seconds> and start an empty one. To get the history back after returning to a newer release, stop nxdns, then in the data directory:

Move the empty querylog.db out of the way.
Delete querylog.db-wal and querylog.db-shm. Left in place, they would corrupt the history you restore.
Rename querylog.db.schema-changed-<unix-seconds> to querylog.db.
Start nxdns.

The configuration file

nxdns reads a configuration file only when --config names it, and never writes it. /etc/nxdns/config.zon is the conventional place, and the packaged systemd unit creates /etc/nxdns and keeps the service from writing to it.

An export, nxdns export --out FILE, is created at mode 0600 because it carries the password hash.

The log file

Only when logging.output = .file. The file is logging.file_path, /var/log/nxdns/nxdns.log by default.

nxdns does not create the log directory; under systemd the packaged unit does. It rotates the file itself at logging.max_size_mb and keeps logging.max_files files, so with the defaults that is nxdns.log and nxdns.log.1 to nxdns.log.4.

Do not rotate this file with logrotate. nxdns keeps writing where it left off, so a rotated file either fills with blank space or stops growing while the old one grows without limit. If another tool must own the log, set logging.output = .stderr and let journald or Docker collect it.

nxdns does not set the log file’s mode. Under the packaged unit, which sets UMask=0077, it is 0600; started from a shell with the usual umask it is readable by every local user.

With logging.output = .stderr or .syslog, nxdns writes to standard error and creates no file.

Certificates and keys

The files doh_server.cert_path, doh_server.key_path, dot_server.cert_path and dot_server.key_path name, /etc/nxdns/cert.pem and /etc/nxdns/key.pem by default. nxdns only reads them. The user nxdns runs as must be able to read both, and nobody else should be able to read the key. nxdns picks up a renewed pair within 30 seconds; see Enable DoH and DoT.