Skip to content
Log inDashboard

Upgrade and back up

Releases are listed in the changelog. Security-relevant node releases are flagged there.

Update notice. The node never updates itself. An enrolled node asks the cloud for the newest release about every six hours; when it runs an older one, its status page shows Update available with both versions, and /api/status has versions.latest and versions.update_available: true. Development builds and standalone nodes show no notice.

Every release image is signed with cosign, and carries a signed SBOM (the list of software inside it, in SPDX format) and SLSA build provenance (a record of how and from what it was built). Verify the image you are about to run, by tag or (better) by the digest listed in the release notes:

Terminal window
cosign verify \
--certificate-identity https://github.com/operomtl/opdns/.github/workflows/release.yml@refs/heads/main \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
ghcr.io/operomtl/opdns-node:<version>
gh attestation verify oci://ghcr.io/operomtl/opdns-node:<version> --repo operomtl/opdns

The two --certificate-… values name who signed: opdns’s release build, which runs on GitHub Actions from the main branch of the opdns source repository. The signature is “keyless”: there is no opdns key to download; the certificate records that identity, and cosign checks it against the public Sigstore transparency log. Copy both values exactly as shown.

cosign verify prints the signature’s claims and exits 0; an image that was not built and signed by opdns’s release build fails. cosign verify-attestation --type spdxjson, with the same two flags, checks the SBOM; gh attestation verify (the GitHub CLI) checks the build provenance. The floating tags (v1.2, v1, latest) point at a signed release digest, so they verify the same way. Run the image by digest (ghcr.io/operomtl/opdns-node:<version>@sha256:…) and set OPDNS_IMAGE to that reference to see it on the status page.

Static binaries ship with a SHA256SUMS file on the release; check them with sha256sum -c SHA256SUMS --ignore-missing (Install the static binary). The binaries are not signed yet.

Container: pull the new version and recreate the container; the volume keeps the identity, the last profile and lists, and the logs.

Terminal window
docker pull ghcr.io/operomtl/opdns-node:<version>
docker rm -f opdns-node
docker run ... # same command, new tag
# or, with Compose: edit the tag, then
docker compose up -d

The image runs as the unprivileged user opdns with the fixed ids 10001:10001, so the volume stays readable across upgrades. Its root filesystem can be read-only: the node writes only to the volume.

Binary: download and verify the new binary as on Install the static binary, replace /usr/local/bin/opdns-node, and sudo systemctl restart opdns-node. The systemd unit grants the port-binding capability itself, so nothing else is needed. If a release changes the unit, replace yours with the new unit file and run sudo systemctl daemon-reload first. Upgrade Unbound with your package manager; the container ships its own pinned Unbound. The node refuses to start with an Unbound older than 1.17.0 (the error names the version it found).

A certificate renewal needs no restart: the node reloads renewed files by itself (certificates). Some configuration keys need none either (reload without a restart).

The node stops cleanly on SIGTERM: it drains its listeners, flushes pending log records, closes the link and stops Unbound.

  • The log database. When a release changes the schema of logs.sqlite, the node first copies the database to backups/pre-v<N>.db in the data directory (N is the old schema version; the copy is skipped, with a warning, when the disk has no room for it), then migrates it in one transaction. A failed migration leaves the database as it was. The node refuses a database written by a newer release, naming the pre-v<N>.db copy to go back to, so a downgrade never misreads it.
  • The configuration file. Its version key says which format it is (1 today). An older file is migrated when it is loaded; a newer one is refused (Configuration).
  • A corrupt database. A database found corrupt at start (after a power cut, say) is moved to backups/corrupt-<time>.db and a fresh one is created; the local page says so. DNS is not affected.

opdns-node backup writes one archive of everything the node cannot fetch again. It is safe while the node runs.

Terminal window
sudo -u opdns opdns-node backup /var/backups/opdns-node.tar.gz
# container:
docker exec opdns-node opdns-node backup /var/lib/opdns/opdns-node-backup.tar.gz
docker cp opdns-node:/var/lib/opdns/opdns-node-backup.tar.gz .

The archive is a .tar.gz written with mode 0600; the command refuses to overwrite an existing file. It holds:

From the data directory Holds
node.json node id and node token
profile.json the last good profile
lists_keys.json list signing keys learnt from the cloud or latest.json
profile_keys.json profile signing keys learnt from the cloud (Profile signing keys)
lists_announced.json the last list version the cloud announced
secrets/ the local API token
logs.sqlite a consistent snapshot of the query log database

lists/ and unbound/ are left out (they are downloaded or regenerated), and so are backups/ and the lock file.

Copying logs.sqlite by hand while the node runs is not safe: recent rows can still be in its -wal file. Use opdns-node backup, or stop the node first.

To move a node to a new host, or to a new container volume:

  1. Stop the old node, and take a fresh backup of it.

  2. Install the node on the new host without starting it.

  3. Restore into its (empty) data directory, then start it:

    Terminal window
    sudo -u opdns opdns-node restore /var/backups/opdns-node.tar.gz
    sudo systemctl start opdns-node

It comes back enrolled, with its profile, list and profile keys and logs. If the node token rotated after the backup was taken, the restored token is no longer valid: enrol the new host again instead. restore takes the data directory’s lock, so it fails while a node runs on that directory. It refuses a directory that already holds an identity or a log database unless you pass --force, accepts only the files backup writes, and checks the database’s integrity before it moves anything into place.

Only one node may use an identity at a time: a second copy running at once replaces the first one’s link session. Without an archive, enrol the new host again instead (Enrol).

Default /var/lib/opdns, created with mode 0700.

Path Holds In the backup
node.json node id and node token (secret, 0600) yes
profile.json last good profile yes
lists/ last good list artifacts no (re-fetched)
lists_keys.json list signing keys learnt from the cloud or latest.json yes
profile_keys.json profile signing keys learnt from the cloud; removed on unenrol yes
lists_announced.json the last list version the cloud announced, so a restart still tells a rollback from an old notice yes
operator_blocks.json, operator_sources.json the last operator blocks the cloud sent, enforced offline no (re-sent with the next profile pull)
archive/ standalone-profile-<time>.json: a standalone profile uploaded at enrolment no
secrets/ api_token, the generated local API token (secret, 0600; standalone mode), and api_token.shown once the page has shown it yes
logs.sqlite (+ -wal, -shm) query logs yes, as a snapshot
backups/ pre-v<N>.db copies taken before a schema migration, corrupt-<time>.db databases moved aside no
unbound/ generated config and root key no

The node refuses to start while node.json or a file under secrets/ is readable by every user of the host (anyone who can read them can act as the node). It writes them 0600; a looser mode comes from a copy or a restore by hand, and the error names the file and the fix:

Terminal window
sudo chmod 600 /var/lib/opdns/node.json /var/lib/opdns/secrets/*

A file readable by its group only is logged as a warning.