Back up and restore PolarBot

What to back up

Not needed:

• The list caches (threatlists/, adultlists/ in the data directory) are downloaded again within a minute of a start.
• The .cred files are encrypted with this machine’s credential key (and its TPM, if it has one), so they cannot be decrypted on another machine. Keep the secrets themselves somewhere safe instead (a password manager): the bot token and client secret can always be reset in the Developer Portal, and a new oauth_key only means servers run /perms authorize again.

The database holds personal data (punishment history). Keep backups as private as the server: install.sh uses a root-only directory (0700) and root-only files (0600). Backups also keep punishment history beyond its 180 days for as long as you keep them; delete old backups.

Back up

With a short stop (simplest, consistent)

STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
sudo install -d -m 0700 /var/backups/polarbot
sudo systemctl stop polarbot
sudo cp -a /var/lib/private/polarbot/polarbot.db "/var/backups/polarbot/polarbot-$STAMP.db"
sudo cp -a /var/lib/private/polarbot/polarbot.db-wal "/var/backups/polarbot/polarbot-$STAMP.db-wal" 2>/dev/null || true
sudo systemctl start polarbot
sudo cp -a /etc/polarbot/config.toml "/var/backups/polarbot/config-$STAMP.toml"

The bot is down for a second or two. Copy /var/backups/polarbot to another machine with your usual backup tool.

While it runs

SQLite can write a consistent copy of a live database. This needs the sqlite3 program (sudo apt install sqlite3 or sudo dnf install sqlite):

STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
sudo install -d -m 0700 /var/backups/polarbot
sudo sqlite3 /var/lib/private/polarbot/polarbot.db "VACUUM INTO '/var/backups/polarbot/polarbot-$STAMP.db'"
sudo chmod 0600 "/var/backups/polarbot/polarbot-$STAMP.db"

VACUUM INTO writes a single, compact file that already contains everything from the write-ahead log. It is safe to run from a daily timer or cron job.

Check a backup

sudo sqlite3 "/var/backups/polarbot/polarbot-$STAMP.db" "PRAGMA integrity_check;"

prints ok.

Restore

Restoring replaces the current database: everything since the backup (new settings, punishments, authorizations) is lost.

sudo systemctl stop polarbot
sudo cp /var/backups/polarbot/polarbot-<STAMP>.db /var/lib/private/polarbot/polarbot.db
sudo rm -f /var/lib/private/polarbot/polarbot.db-wal /var/lib/private/polarbot/polarbot.db-shm
sudo cp /var/backups/polarbot/polarbot-<STAMP>.db-wal /var/lib/private/polarbot/polarbot.db-wal 2>/dev/null || true
sudo sh -c 'chown --reference=/var/lib/private/polarbot /var/lib/private/polarbot/polarbot.db* && chmod 0600 /var/lib/private/polarbot/polarbot.db*'
sudo systemctl start polarbot
sudo journalctl -u polarbot -n 20 --no-pager

• Replace <STAMP> with the backup’s time stamp (ls /var/backups/polarbot).
• The old -wal and -shm files belong to the database you are replacing and must go; the backup’s own -wal (only backups made by install.sh or the stop method may have one) goes with it.
• chown --reference gives the files to the service’s user, which owns the directory. It runs in sh -c because only root can list /var/lib/private, so your own shell could not expand the *.

The binary must be the same version or newer than the one that wrote the backup. An older binary refuses to start on a database migrated by a newer one (see Roll back).

On a new machine

1. Install PolarBot (steps 1–8; enter the secrets again, they do not move with the backup), and start it once so systemd creates the data directory.
2. Restore the database as above, and your config file to /etc/polarbot/config.toml.
3. The new machine has a new oauth_key, so the stored authorizations cannot be decrypted: each server’s Owner runs /perms authorize again. Point the callback host name’s DNS at the new machine and set up nginx there.