milestone 13: restructure docs to diataxis, tutorial, every command executed
This commit is contained in:
@@ -0,0 +1,192 @@
|
||||
# Back up and restore
|
||||
|
||||
The configuration database is the only state worth keeping. `nxdns export`
|
||||
writes it out as a ZON file and `nxdns import` writes one back. The query log is
|
||||
deliberately not part of a backup: it is expendable history, and if it is
|
||||
missing it gets recreated empty.
|
||||
|
||||
The commands below use the scratch lab from
|
||||
[enable DoH and DoT](enable-doh-and-dot.md), data directory
|
||||
`/tmp/nxdns-lab/data`. On a real install drop `--data-dir` and the default
|
||||
`/var/lib/nxdns` applies.
|
||||
|
||||
## Back up
|
||||
|
||||
One command, against a stopped or a running server:
|
||||
|
||||
```sh
|
||||
nxdns export --data-dir /tmp/nxdns-lab/data --out /tmp/nxdns-lab/backup.zon
|
||||
```
|
||||
|
||||
```
|
||||
wrote /tmp/nxdns-lab/backup.zon
|
||||
```
|
||||
|
||||
The write is a temp file plus a rename, so an interrupted export leaves no
|
||||
half-written backup, and the result is mode 0600:
|
||||
|
||||
```sh
|
||||
stat -c '%a %n' /tmp/nxdns-lab/backup.zon
|
||||
```
|
||||
|
||||
```
|
||||
600 /tmp/nxdns-lab/backup.zon
|
||||
```
|
||||
|
||||
That mode is not decoration. The file carries `web.password_hash`:
|
||||
|
||||
```sh
|
||||
grep password /tmp/nxdns-lab/backup.zon
|
||||
```
|
||||
|
||||
```
|
||||
.password = "",
|
||||
.password_hash = "$argon2id$v=19$m=19456,t=2,p=1$Gh+zg9xke6BqSVOiouRbqG50+Bs8ZGcXA6oKgs7lrKg$crTNMu5OI8yKBkp31r4+Y1OUQmLiAlH/qvsIxjBQRq4",
|
||||
```
|
||||
|
||||
Treat backups as secrets. `.password` is always exported as `""` — the
|
||||
plaintext is never stored anywhere — so the file re-imports without anyone
|
||||
knowing the password.
|
||||
|
||||
Without `--out` the export goes to stdout, where the file mode is your
|
||||
redirect's problem:
|
||||
|
||||
```sh
|
||||
nxdns export --data-dir /tmp/nxdns-lab/data | head -6
|
||||
```
|
||||
|
||||
```
|
||||
// nxdns configuration
|
||||
// generated by `nxdns export` — the database is the source of truth
|
||||
.{
|
||||
.upstream = .{ .read_timeout_ms = 3000, .total_timeout_ms = 5000 },
|
||||
.dns = .{
|
||||
.bind_ipv4 = "127.0.0.1",
|
||||
```
|
||||
|
||||
Runtime facts are left out on purpose: client first-seen and last-seen times,
|
||||
rule creation times, per-source domain counts and checksums. They are things a
|
||||
running server produces, not configuration, and including them would make two
|
||||
exports taken minutes apart differ.
|
||||
|
||||
## Restore onto a fresh data directory
|
||||
|
||||
This is the normal restore: new machine, new disk, empty data directory. No
|
||||
`--force`, because there is nothing to overwrite.
|
||||
|
||||
```sh
|
||||
nxdns import /tmp/nxdns-lab/backup.zon --data-dir /tmp/nxdns-lab/data-restored
|
||||
```
|
||||
|
||||
```
|
||||
info(migrations): config.db migrated from schema version 0 to 2
|
||||
imported /tmp/nxdns-lab/backup.zon
|
||||
```
|
||||
|
||||
The migration line is expected: `import` creates and migrates the database
|
||||
before writing to it.
|
||||
|
||||
## Restore over an existing database
|
||||
|
||||
`import` refuses a database that already has content, so a plain `import` can
|
||||
never clobber a configured server by accident:
|
||||
|
||||
```sh
|
||||
nxdns import /tmp/nxdns-lab/backup.zon --data-dir /tmp/nxdns-lab/data
|
||||
```
|
||||
|
||||
```
|
||||
import failed: DatabaseNotEmpty
|
||||
```
|
||||
|
||||
That exits 2. Say `--force` when replacing is what you mean:
|
||||
|
||||
```sh
|
||||
nxdns import /tmp/nxdns-lab/backup.zon --force --data-dir /tmp/nxdns-lab/data
|
||||
```
|
||||
|
||||
```
|
||||
imported /tmp/nxdns-lab/backup.zon
|
||||
```
|
||||
|
||||
Stop the server first. `import` replaces the whole configuration underneath a
|
||||
process that has already read it, and a running server will not notice.
|
||||
|
||||
On a real install that is the systemd unit:
|
||||
|
||||
```sh
|
||||
systemctl stop nxdns
|
||||
nxdns import /var/backups/nxdns-config.zon --force
|
||||
systemctl start nxdns
|
||||
```
|
||||
|
||||
**Not verified on this host.** Those three lines are the only commands on this
|
||||
page that were not run: this machine has no installed nxdns systemd unit
|
||||
(`systemctl status nxdns` answers `Unit nxdns.service could not be found.`) and
|
||||
`systemctl stop`/`start` need root. The lab equivalent below was run, and it
|
||||
exercises the same stop-import-start sequence. In the lab the server is a
|
||||
foreground `nxdns run`, so stopping it is Ctrl-C in its own terminal:
|
||||
|
||||
```sh
|
||||
nxdns export --data-dir /tmp/nxdns-lab/data --out /tmp/nxdns-lab/pre-restore.zon
|
||||
# Ctrl-C the `nxdns run` terminal, or `kill` its pid from another shell
|
||||
nxdns import /tmp/nxdns-lab/pre-restore.zon --force --data-dir /tmp/nxdns-lab/data
|
||||
nxdns run --data-dir /tmp/nxdns-lab/data --config /tmp/nxdns-lab/etc/config.zon
|
||||
```
|
||||
|
||||
```
|
||||
wrote /tmp/nxdns-lab/pre-restore.zon
|
||||
imported /tmp/nxdns-lab/pre-restore.zon
|
||||
```
|
||||
|
||||
## Verify a backup
|
||||
|
||||
The round trip is byte-stable: exporting, importing and exporting again gives
|
||||
an identical file. That is the cheapest check that a backup is complete and
|
||||
that it will load.
|
||||
|
||||
```sh
|
||||
nxdns export --data-dir /tmp/nxdns-lab/data --out /tmp/nxdns-lab/backup2.zon
|
||||
diff /tmp/nxdns-lab/backup.zon /tmp/nxdns-lab/backup2.zon \
|
||||
&& echo "round trip is byte-identical"
|
||||
```
|
||||
|
||||
```
|
||||
wrote /tmp/nxdns-lab/backup2.zon
|
||||
round trip is byte-identical
|
||||
```
|
||||
|
||||
The same check works across data directories — export from the restored copy
|
||||
and diff against the backup you restored from:
|
||||
|
||||
```sh
|
||||
nxdns export --data-dir /tmp/nxdns-lab/data-restored --out /tmp/nxdns-lab/backup3.zon
|
||||
diff /tmp/nxdns-lab/backup.zon /tmp/nxdns-lab/backup3.zon \
|
||||
&& echo "restored database exports identically"
|
||||
```
|
||||
|
||||
```
|
||||
wrote /tmp/nxdns-lab/backup3.zon
|
||||
restored database exports identically
|
||||
```
|
||||
|
||||
## What is not in the backup
|
||||
|
||||
Everything under the data directory other than `config.db`:
|
||||
|
||||
- `querylog.db` — expendable history, recreated empty when absent.
|
||||
- `blocklists/` — compiled snapshots. They are rebuilt from the sources named in
|
||||
the configuration, so restoring the configuration is enough; the first refresh
|
||||
after a restore downloads them again.
|
||||
|
||||
The data directory layout is in
|
||||
[files and directories](../reference/files-and-directories.md).
|
||||
|
||||
## A backup before every upgrade
|
||||
|
||||
There is no downgrade path. Schema migrations run forward automatically at
|
||||
startup and before `check`, `export` and `import`; nothing walks them back. Take
|
||||
an export before installing a new binary — see [upgrade](upgrade.md).
|
||||
|
||||
Every command on this page was executed on this host as written, except the
|
||||
`systemctl` block marked **Not verified on this host** above.
|
||||
Reference in New Issue
Block a user