How Backup Works¶

This page explains the concepts behind a Vault backup. For the exact field names and options you set on a job, see the Job Configuration reference.

Backup sources¶

A Vault job backs up one or more sources on your Unraid host:

Docker containers — the container image, its XML template, and every mapped appdata volume. You can exclude specific paths per container.
libvirt VMs — captured in live-snapshot or cold mode, with NVRAM preserved.
ZFS datasets — using native zfs send/receive with snapshot management.
Folders and plugins — any path on the host, plus all installed Unraid plugins.

Vault also performs stale-item detection: when a source disappears from the host, it is flagged so jobs stay clean rather than silently failing.

Backup strategies¶

Vault supports three backup strategies that trade off speed against storage:

Full — a complete, self-contained copy of every source. A full backup depends on nothing else.
Incremental — captures only what changed since the previous backup (full or incremental) in the chain. Incrementals are small and fast but must be replayed in order on top of their parent full.
Differential — captures everything that changed since the last full backup. Each differential is larger than an incremental but only ever depends on a single full.

Chains form from these building blocks: a full backup anchors the chain, and subsequent incremental or differential runs attach to it. Restoring reconstructs a point in time by combining the anchoring full with the necessary incrementals or the relevant differential.

The first run is always a full backup

Selecting Incremental or Differential on a brand-new job is safe: the very first run automatically performs a Full backup (there is nothing yet for an increment to attach to), and only subsequent runs capture changes — Full → Incremental → Incremental → …. You do not need to run a manual Full first before switching the job to Incremental.

Retention¶

Retention decides how many backups to keep and which to prune. Vault offers two models:

Simple count — keep the most recent N backups and prune the rest.
Long-Term Retention (LTR) — bucketed retention that keeps backups across multiple time horizons. Buckets are keep_latest, daily, weekly, monthly, and yearly, so you can retain, for example, the last few runs plus one per day, week, month, and year.

For the exact retention fields on a job, see the Job Configuration reference.

Encryption¶

Backups can be encrypted with your backup password using age encryption — a modern, audited standard. Encryption is applied to the backup content and to run manifests (manifest.json) so that data at rest and backup metadata (such as job name, items, and settings) on the storage destination cannot be read without the password.

For deduplicated storage destinations, manifests are automatically encrypted using AES-256-GCM keyed off the destination's master key, keeping metadata protected without extra user intervention.

Deduplication¶

Vault uses content-defined deduplication (Keyed-FastCDC with a per-destination dedup repository) so that repeated data across runs and sources is stored only once. This reduces the storage footprint of backup chains. Maintenance helpers vault dedup gc and vault dedup repair are available for garbage collection and repository repair.

Staging work area¶

When creating classic compressed archives (such as folder items), Vault temporarily assembles the archive in a local staging directory before finalizing it.

Staging path selection follows a prioritized cascade:

Custom staging override — if configured under Settings > Temporary Work Area.
Destination-adjacent staging — if the destination is a local path with Stage temporary backups beside this destination enabled, staging happens in a hidden .vault-stage directory on that disk.
Cache pools — Unraid SSD/NVMe cache pools (/mnt/cache, /mnt/fast_nvme, etc.), ranked by available free space.
Local storage destination — local backup storage disks.
System temporary directory — /tmp or OS default temp dir.

Staged archives are automatically cleaned up when the run finishes or upon daemon startup if a previous run was abruptly interrupted.

Verification¶

Every run produces a SHA-256 verification of what was written, and you can trigger an on-demand verify of any restore point. Verification confirms that stored backup data matches what Vault expects, so you find integrity problems before you need to restore.

Progress¶

While a job runs, the dashboard shows what the current item is actually doing: its phase (scanning, preparing, processing, transferring, verifying, or finalizing) and the real work done in that phase, for example Uploading 84.2 GB / 225 GB — 37% with the transfer rate and, once enough of the phase has passed, an estimate of the time left. A phase whose total is not known yet shows the phase and its counters without a percentage. Folder backups scan the source first, so archiving and chunking have a real total; container volumes, whose combined size is only known once they have been read, show live bytes and files instead. If nothing moves for two minutes, the card says how long it has been quiet, so a slow but healthy upload can be told apart from a stalled one. The same information is available from GET /api/v1/runner/status and the MCP get_runner_status tool (see Progress).