Backup

Backup jobs with schedule and retention: rsync, S3 (rclone) and appdata snapshots, restore.

Jobs

Backup → New job. Every job has a name, a kind, an optional schedule (hourly, daily, weekly, monthly; server local time) and a retention. History shows the last 50 runs with result, amount transferred, duration and log; running jobs show their step and progress and can be cancelled. Test target checks connection and credentials without transferring data.

Kind	What happens
rsync	Folders are mirrored with rsync over SSH (Bunkerbox key) or to an rsync daemon.
S3 (rclone)	Folders are uploaded with rclone sync to an S3-compatible bucket, optionally encrypted on the client (rclone crypt).
Appdata snapshot	The selected apps and containers/VMs are stopped, the datasets are snapshotted recursively with ZFS and everything is started again; optionally the snapshot is then transferred via rsync or S3.

Sources of rsync and S3 jobs must be in a mounted dataset, below /appdata or below /mnt/remotes. Each folder ends up under its own name on the target (/tank/documents → <target>/documents), so the names must be unique.

A failed run raises the notification "backup failed" (see Notifications). While a job runs, updates wait. Runs interrupted by a restart of Bunkerbox are marked as failed; apps and instances they had stopped are started again.

rsync targets

• SSH: under Backup → SSH key Bunkerbox generates an ed25519 key once (/appdata/bunkerbox/data/backup/ssh/, root only). Add the public key to ~/.ssh/authorized_keys of the target user on the server. The server's host key is stored on first contact (StrictHostKeyChecking=accept-new, own known_hosts); if it changes later, the backup fails. The target path is created when needed.
• rsync daemon: rsync://[user@]server:port/module/path. A module password is stored readable for root only and passed with --password-file.
• Delete: optionally rsync deletes files on the target that were deleted in the source (--delete).
• Bandwidth: optional limit in KiB/s.

S3 targets

Endpoint (https; http only for servers in the local network), region, bucket, optional prefix, access key ID and secret access key. With encryption Bunkerbox puts an rclone crypt remote on top of bucket/prefix; content and optionally file and folder names are encrypted before the upload. Without the encryption password the data cannot be restored – keep it somewhere outside the NAS as well.

Secrets (secret key, encryption and module password) are stored only in /appdata/bunkerbox/data/backup/secrets/<job>.json (directory 700, file 600) and are never shown. When editing, they are kept if the field stays empty. For every run Bunkerbox writes a temporary rclone config (600) and deletes it afterwards.

Retention

The rules last, daily, weekly and monthly keep the newest states, or the newest state per day, week (starting Monday) and month; everything else is deleted.

• rsync and S3: changed and deleted files move into <target>/.bunkerbox-versions/<YYYYMMDD-hhmmss>/ per run. The rules decide which of these version folders stay. With all rules at 0 the target is a plain mirror without versions.
• Appdata: the rules apply to the snapshots <dataset>@backup-<job>-<YYYYMMDD-hhmmss> of this job (at least one rule must be greater than 0). Other snapshots are left alone.

Appdata snapshots

1. The selected apps that are running are stopped with docker compose down, the selected containers and VMs are stopped. If an instance cannot be stopped, it is backed up while running and the run ends with a warning.
2. Every selected dataset is snapshotted recursively (including own datasets of single apps below /appdata/<app>).
3. Everything that was running is started again – also when the snapshot or stopping an app fails halfway. Whatever cannot be started again is named in the notification. Before each stop Bunkerbox records what the run stopped; if Bunkerbox is restarted during the run, it starts these apps and instances again on the next start.
4. Optionally the snapshot content (<mountpoint>/.zfs/snapshot/<snapshot>/) is transferred per dataset to <target>/<dataset>/. Datasets without a mountpoint are skipped and logged as a warning – this applies to the volumes of Incus instances (containers with mountpoint=legacy, VMs as zvols). Instances are therefore only kept as local snapshots; for an off-site copy, export them (incus export) into a share that an rsync or S3 job picks up.
5. Old snapshots of the job are removed according to the retention.

The pause usually takes only seconds because a ZFS snapshot is instant; the transfer happens afterwards.

Restore

Backup → Restore lists the snapshots of all appdata jobs.

• Restore apps: the selected app directories /appdata/<app> are copied back from the snapshot with rsync --delete. Running apps are stopped for it and started afterwards. This always works, also when Bunkerbox itself lives in the same dataset.
• Rollback: the dataset and its child datasets with the same snapshot are reset completely with zfs rollback. Newer snapshots are lost and must be confirmed explicitly. If Bunkerbox itself (/appdata/bunkerbox) lives in the dataset, the rollback is blocked – it would reset the running installation. Not only the apps and instances of the job are stopped, but every one whose data lies in one of the rolled-back datasets (/appdata/<app> or the instance's volume in the pool).

Both are confirmed with the snapshot name and appear in the job history.

Restoring from external targets (manual)

• rsync: fetch the data with rsync -a <user>@<server>:<path>/<folder>/ /target/; older states of single files are under .bunkerbox-versions/.
• S3 without encryption: rclone copy with an S3 remote on bucket/prefix/<folder>.
• S3 with encryption: create a crypt remote with the same password and the same name encryption on top of bucket/prefix (rclone config), then rclone copy crypt:<folder> /target/.
• Transferred appdata snapshots: are stored as plain folders below <target>/<dataset>/. Stop the apps, copy the directory back, start the apps.