Skip to content

Docs / RivetMSP / Deploying & administering

Backups and disaster recovery

Encrypted scheduled backups, restoring onto a new server, and testing a restore safely.

RivetMSP ships tooling for scheduled, encrypted backups and for restoring them onto a server. A backup you have never restored is a backup you do not really have, so test the restore as well.

The two kinds of backup#

deploy/backup.sh + timer In-app backup
Where Command line, run by a systemd timer Settings > Backup
Encrypted Yes (AES-256) No
Scheduled Yes No, on demand only
Use it for Disaster recovery A quick snapshot before a risky change

The in-app backup is handy but does not replace the scheduled one. The two coexist in the same backups/ directory without deleting each other's files.

Set up scheduled backups#

Backups are encrypted with a passphrase that lives only in a root-only file on the server. It is never on the command line and never in the systemd unit.

sudo mkdir -p /etc/itflow
sudo bash -c 'openssl rand -base64 48 > /etc/itflow/backup-passphrase'
sudo chmod 600 /etc/itflow/backup-passphrase
sudo chown root:root /etc/itflow/backup-passphrase

Immediately copy that passphrase somewhere other than this server: a password manager, a printed copy in a safe, a secrets vault. An encrypted backup whose only passphrase sits on the same disk gives you no protection if that disk is lost, stolen or encrypted by ransomware.

Run a backup by hand once to confirm it works and to see where it writes:

sudo deploy/backup.sh --app-dir=/var/www/msp.example.com --passphrase-file=/etc/itflow/backup-passphrase

Then enable the timer and confirm the next run:

sudo systemctl enable --now itflow-backup.timer
sudo systemctl list-timers itflow-backup.timer

What is in a backup#

Each run writes one file named backup-<dbname>-<timestamp>.tar.gz.enc. It is a tar archive encrypted with openssl enc -aes-256-cbc -pbkdf2 and contains:

  • the database dump,
  • a small backup-manifest.json with the installation ID and, if you set one, the settings encryption key,
  • the uploads/ directory.

Copy the encrypted file off the server too. A backup on the same machine does not survive losing the machine.

Restore#

deploy/restore.sh decrypts an archive and overwrites an already-installed instance's database and uploads.

sudo deploy/restore.sh --app-dir=/var/www/msp.example.com \
    --backup=/path/to/backup-msp-20260101T023000Z.tar.gz.enc \
    --passphrase-file=/etc/itflow/backup-passphrase \
    --confirm-restore

In order, it:

  1. Takes a safety backup of the target's current state (skip only if the target has nothing worth keeping).
  2. Decrypts and extracts the archive.
  3. Recovers the manifest, if the archive has one.
  4. Drops and recreates the database, then imports the dump. This is deliberately not a plain import, so a table that exists on the target but not in an older backup does not survive.
  5. Replaces uploads/ and restores ownership and permissions.
  6. Re-applies the settings encryption key from the manifest, if there was one. That key lives only in config.php, never in the database, so without the manifest a restore would silently corrupt every setting it protected.

Credential vault data is encrypted with each user's own key, derived from their password. As long as the admin's password is unchanged after the restore, vault data decrypts normally.

Test a restore safely#

Restore into a disposable second instance, not production:

sudo deploy/install.sh --domain=scratch.example.com
sudo deploy/restore.sh --app-dir=/var/www/scratch.example.com --backup=... --passphrase-file=... --confirm-restore

Check that you can sign in and see your data, then delete the scratch instance. There is no dry-run mode; the isolation comes from which --app-dir you point at.

This guide is maintained by Rivet IT Ops. Found a mistake? Tell us. RivetMSP on GitHub