# 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

```sh
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:

```zon
        .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:

```sh
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](install-with-docker.md#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.

```sh
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`:

```sh
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:

```sh
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](../reference/files-and-directories.md) lists everything in the data directory.