Restoring Data

Breeze supports several restore methods depending on what you need to recover — from a single file to a complete system.

S3 restores need HTTPS

Restores and verification from S3 or S3-compatible storage need the v0.118 agent or later, an HTTPS agent API and an HTTPS storage endpoint. See HTTPS for Restores.

---

Browsing Snapshots

Before restoring, you can inspect what a snapshot contains:

1. Go to Backup > Device Backup.
2. Find the device in the job list or device backup tab.
3. Open the Snapshot Browser and select a snapshot from the dropdown.
4. Navigate the file tree — expand folders to see their contents, including file names, sizes, and modification dates.

Note

Non-file snapshots are badged by type in the browser — a system-state snapshot shows a System image badge in both the snapshot selector and the detail header, so you can tell it apart from a file backup at a glance.

A system_image snapshot taken by a v0.112.0 or later agent on Linux or Windows also carries a restorability verdict in the detail header: a green Bare-metal restorable badge, or an amber Not bare-metal restorable badge whose tooltip lists why (BIOS/MBR boot, LVM, LUKS, RAID, btrfs root, ZFS, multi-disk OS, or no layout captured). The verdict tells you whether breeze-backup rebuild can reproduce the machine’s disk from that snapshot; ordinary restores and bmr-recover are not affected by it. File-only and macOS snapshots show no badge.

Tip

Always browse a snapshot before restoring to confirm the files you need are present. This is especially useful when deciding between a full restore and a selective one.

---

Restore Types

Type	What it recovers	When to use
Full restore	Everything in the snapshot	Replacing a failed drive or rebuilding a system
Selective restore	Individual files you choose (not folders — see below)	Recovering accidentally deleted files
Bare metal recovery	Files and/or OS state (registry or /etc, services, firewall, scheduled tasks, packages) onto a machine that reinstalls or boots its own OS — or, on Linux, a full disk rebuild from a whole-machine snapshot	Replacing a dead machine entirely. See Bare Metal Recovery

---

Running a Restore

Full Restore

1. Go to Backup → Restore in the console to open the Restore Wizard.
2. Select the snapshot to restore from.
3. Choose Full Restore.
4. Choose the destination:
   • Staging folder on the device — the default. Files are restored under the device’s system temp directory (breeze-restore/<original path>); the originals are never overwritten. (Earlier releases labelled this option “Original location”, which it never was.) To restore in place — overwriting the originals — choose Alternate path and type in the original root path yourself.
   • Alternate path — specify a directory (e.g., /var/restore or D:\Restored); files are written there preserving their relative structure.
5. Review the summary and click Restore. The restore always runs on the device that owns the snapshot — the wizard does not offer a way to target a different device (see Cross-Device Restore below).

Selective Restore

1. Go to Backup → Restore in the console to open the Restore Wizard. (The Snapshots tab links to it from the snapshot file list.)
2. Select the snapshot.
3. Choose Selective Restore.
4. Browse the file tree and check the boxes next to the individual files you want to recover. Selection is per-file — checking a folder is not supported, and the API rejects a folder path submitted directly; select the files inside it instead.
5. Choose the destination path (see the staging-folder default above).
6. Review and click Restore.

Caution

Selective restore currently matches files by path prefix, not by exact folder boundary. If you select /home/alice, a sibling folder like /home/alice2 or /home/alice-old is also included in the restore, since its path starts with the same characters. Review the file list carefully before confirming a selective restore of folders with similar names.

---

Monitoring a Restore

After you start a restore, the job appears in restore history and on the target device’s Backup tab. You can track it from:

• The Backup dashboard’s Recent Jobs section
• The target device’s Backup tab

Completed restore jobs show the final status, restored file count, restored byte count, and any structured warnings or errors reported by the agent.

If the target device is offline, Breeze rejects the restore request immediately instead of creating a pending restore that cannot run.

---

How restores reach storage

v0.118.0+. Restore commands no longer carry your storage credentials. This covers file restores, verification and test restores, SQL Server restores and verification, Hyper-V restores, restore as VM, and instant boot. Breeze looks up the storage destination when it delivers the command, not when you start it.

With the 0.118 backup helper, the device does not receive the storage destination at all. Instead:

1. Breeze issues a short-lived, read-only storage session for that one command on that one device.
2. For each file it needs, the helper asks Breeze for a download link. Breeze checks that the file belongs to the snapshot being restored, then returns a link that expires within minutes.
3. The helper downloads the file directly from storage over that link, and renews the session for as long as the restore runs.

Breeze uses this path when all of these hold:

• the device’s backup helper is 0.118.0 or later;
• the snapshot is on S3-compatible storage reached over HTTPS, and its storage location still matches the destination’s current settings;
• the server address the device uses is HTTPS;
• Breeze has a verified file list for the snapshot (it builds one automatically when it is missing), or, for SQL Server, the snapshot’s manifest and backup file.

Otherwise the restore uses the previous path, where the device receives the storage destination with the command. This is the case for devices whose backup helper predates 0.118 until they update. Restores keep working either way.

Note

A backup, restore or verify command still queued when its device moves to another organization, including during an organization merge, is not delivered. It is expired with a reason. Run it again after the move.

Tip

Self-hosted operators can see which path each restore took from the breeze_backup_read_dispatch_total metric on /metrics. Its mode label is brokered (storage session) or legacy (previous path), and its reason label says why.

---

Integrity checks on restore

v0.120.0+. Every restore, verification, test restore, SQL Server restore, Hyper-V restore, restore as VM, instant boot and bare-metal recovery carries what Breeze knows about the snapshot’s attestation: the exact size and SHA-256 of its manifest (and, for whole-machine snapshots, its disk layout and system-state manifest), or why the snapshot has none.

Attested snapshots. With a v0.120.0 or later backup helper on the device:

• The manifest, layout and system-state manifest are checked against the attestation before they are read.
• Every restored file must match its manifest entry exactly, size and SHA-256. A file whose entry has no checksum fails (missing_checksum).
• Each file is downloaded to a staging file next to its destination and moved into place only after it passes, so a file that fails is never written over anything.
• If a vault copy does not match, the helper reads the file from primary storage instead and adds a warning (vault copy differs from backup; restored from primary storage).

A failed check is reported with a result code such as checksum_mismatch, size_mismatch, integrity_mismatch, missing_checksum or not_attested, shown on the restore as Result code: ….

Snapshots that failed their integrity check are refused. If a snapshot’s stored objects did not match its attestation, Breeze will not deliver any restore, verification or VM restore from it. The command fails with This backup did not match its integrity record and cannot be read from storage. (or The stored backup does not match its integrity record…). A restore already running from such a snapshot is stopped at its next storage request. If only the snapshot’s file list was built before its attestation existed, Breeze rebuilds the list and the message says so; run the restore again afterwards.

Restores require a backup helper that checks attestations. A restore that writes, imports or boots a backup (file restore, SQL Server restore, Hyper-V restore, restore as VM, instant boot, bare-metal recovery and rebuild) is sent only to a device whose backup helper reports it checks restores against attestations (Breeze agent v0.120.0 or later). An older device is refused when you start the restore, and again if the device was downgraded before the command was delivered: Update the Breeze agent on this device, then try again. Bare-metal recovery media and recovery tools older than v0.120.0 are refused at code exchange and authentication: This recovery tool is too old to check backup integrity. Download current recovery media or the current recovery tool, then try again. Verification and test restore are not affected.

Unattested snapshots need a confirmation. A snapshot with no attestation (taken before attestations existed, or by an older helper) is labelled Not verified in the restore wizards. Restoring it requires a technician to confirm it with two-factor authentication (or, on a deployment with two-factor authentication disabled, an explicit confirmation). A technician who has not set up a second factor is asked to set one up first (an authenticator app or a passkey, from their profile), then retries the restore and confirms it. The confirmation applies to that one snapshot, target device and restore type, is recorded in the audit log as backup.restore.unattested_override (with the confirmation method), and the restore result carries the warning Unattested snapshot: files were not checked against a snapshot attestation. The same confirmation is needed to restore a backup kept on a device’s own disk onto a different device. AI-initiated restores and DR plan executions cannot confirm and are refused for such snapshots; start them from the console.

Snapshots still being checked wait. A restore of a snapshot whose attestation is still being verified is refused with This backup is still being checked. Try again in a few minutes.; a queued restore waits for the check.

Verification and test restore of an unattested snapshot still run without confirmation; their result says the snapshot is unattested.

Tip

Self-hosted operators can track this from the breeze_backup_restore_integrity_total metric on /metrics. Its type label is the command type (or recovery_bootstrap), status is attested, unattested, override, refused or absent, and reason says why.

---

Cross-Device Restore

The restore API (POST /backup/restore) accepts a target deviceId, so a snapshot can be restored to a different device than the one it was taken from — both devices must be in the same organization. This is API-only today: the Restore Wizard in the web UI never sends a deviceId, so any restore started from the wizard runs on the device that owns the snapshot. To restore to a different device, call the API directly with the target deviceId.

Cross-device restores also require the destination device to be online when you start the restore. If Breeze cannot queue the restore command, the restore job is marked failed with the dispatch error instead of remaining stuck in a pending state.

---

What Is and Isn’t Preserved

• Preserved — file content byte-for-byte; on Linux and macOS, Unix mode permission bits and the original modification time (mtime) are reapplied to each restored file.
• Not preserved — symlinks are skipped entirely, both in the backup and on restore; empty directories are not recreated; setuid/setgid/sticky bits are dropped (only the base permission bits are restored).
• Open files. On Windows, files locked by running applications may fail to restore. Stop the relevant services first, or restore to an alternate path.
• Windows names. A path component that contains :, ends in . or a space, or is a reserved device name (CON, NUL, COM1, …) is refused with invalid_windows_name. This applies to file restores, bare-metal recovery, VM file restore and Hyper-V restore.
• Windows permissions. A recorded security descriptor is applied only when every owner, group and access-list account is one the machine recognises (a well-known account, the local machine, its domain or a trusted domain). Otherwise, or when the recorded descriptor cannot be read, the item gets a restrictive access list: owner Administrators, access for SYSTEM and Administrators only. The restore result shows N items restored with a restrictive access list with the affected paths (up to 100 listed); review and reassign their permissions. When only an auditing (SACL) entry names an unknown account, the descriptor is applied without its auditing entries. A whole-machine rebuild applies descriptors as recorded.

---

Restore Considerations

• Destination path. See the staging-folder default above — an explicit destination path is the only way to control where files land, including restoring in place.
• Permissions. See “What Is and Isn’t Preserved” above. If restoring to a different device or OS, permissions may need adjustment regardless.
• Disk space. Ensure the target device has enough free space for the restore. The snapshot’s total size is shown in the Restore Wizard summary.