Skip to content
cerberd

Upgrades

An upgrade replaces the binary and restarts the daemon. A restart doesn’t touch wg0: the new daemon adopts the live interface and reconciles, so clients see no interruption.

Steps

Section titled “Steps”

  1. Back up the database (it is safe while the daemon runs):

    Terminal window
    cerberd db backup wg0 /root/wg0-$(date +%F).db

  2. Install the new release as in Installation: unpack the tarball and run ./install.sh. It replaces the binary and the unit file and runs systemctl daemon-reload. It doesn’t restart anything, and it doesn’t touch your files in /etc/cerberd/.

  3. Restart each instance:

    Terminal window
    systemctl restart cerberd@wg0

  4. Check:

    Terminal window
    cerberd --version                  # the installed binary
    cerberd status                     # first line ends with the daemon's version
    journalctl -u cerberd@wg0 -n 20

    Until you restart, cerberd status warns that the daemon runs a different version than the binary:

    the daemon runs v1.3.2, this binary is v1.4.0: restart cerberd@wg0 to run it

If the daemon doesn’t come back

Section titled “If the daemon doesn’t come back”

systemctl status cerberd@wg0 showing exit code 78 means a setup error: systemd doesn’t retry it. wg0 keeps forwarding meanwhile. The journal says what is wrong. Common cases after an upgrade:

  • A config key was removed or moved. The message names the key and where it went. Edit /etc/cerberd/wg0.yaml and restart. Release notes list such changes.
  • An unknown key. Unknown keys are rejected rather than ignored. Check spelling against Configuration.

Database schema

Section titled “Database schema”

The schema is pushed on every start (CREATE TABLE IF NOT EXISTS); there are no migrations to run. Additive changes keep the schema version. An incompatible change bumps it (PRAGMA user_version), and an older cerberd then refuses the database:

database /var/lib/cerberd/wg0.db has schema version 2; this cerberd knows 1 (upgrade cerberd)

Rollback

Section titled “Rollback”

Reinstall the previous release with its install.sh and restart. If the newer version bumped the schema, restore the backup you took in step 1 as well:

Terminal window
systemctl stop cerberd@wg0                               # wg0 stays up
rm -f /var/lib/cerberd/wg0.db-wal /var/lib/cerberd/wg0.db-shm
install -m600 -o cerberd -g cerberd /root/wg0-2026-10-24.db /var/lib/cerberd/wg0.db
systemctl start cerberd@wg0

Peers changed after the backup are lost; the reconciler then makes wg0 match the restored database (within the hub.max_removals guard). See Backup and restore.