# Backups and disaster recovery

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.

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

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

```bash
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.

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

```bash
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.
