Bare Metal Recovery

Bare Metal Recovery (BMR) has two modes.

• Recover from Breeze recovery media (Linux). Download the release-built Linux ISO, boot the target machine from it, and enter a one-time nine-character code from the console. The media partitions the blank disk from the layout recorded with the snapshot, restores a whole-machine snapshot into it, applies the OS state offline, installs the bootloader and reboots into the rebuilt system. Progress is reported live on the recovery’s timeline in Breeze. This is the path for a dead disk or replacement hardware; see Recover from Breeze recovery media.
• Reinstall-then-recover (all platforms). You put a working OS on the target machine yourself, then run the breeze-backup recovery binary with a one-time token. A file snapshot restores its files onto whatever is booted; a system_image snapshot downloads the OS-state artifacts collected at backup time, verifies each one, and applies them to the booted OS (registry hives, /etc, packages, services, firewall rules, scheduled tasks — see What gets applied). There is no WinPE/WinRE environment yet: on Windows and macOS this is the only mode, and you provide the booted OS before recovery starts. See Alternative: recover into a freshly installed OS.

Both modes share the same rebuild engine, breeze-backup rebuild, which is also available as a command-line tool for scripted or unusual recoveries.

A recovery token is scoped to one snapshot. A file-mode snapshot recovers data; a system_image-mode snapshot applies OS state. To recover both for one machine, generate two tokens (one per snapshot) and run bmr-recover twice, or back the machine up with a Whole machine profile so one snapshot carries both — a whole-machine profile is a single system_image selection that also walks the OS root, so it produces exactly one snapshot with files, layout, and system state together, not a separate file snapshot plus a files-less system_image snapshot.

Tip

Recovering from an incremental snapshot — one that reuses files unchanged since an earlier snapshot instead of re-uploading them — works the same as recovering from a full snapshot, in every mode on this page. Breeze resolves those cross-snapshot references automatically at recovery time.

---

Recover from Breeze recovery media

This is the fully guided path. It needs a whole-machine snapshot that Breeze marked Bare-metal restorable (see Is the snapshot bare-metal restorable?) and a target machine that boots UEFI with one blank disk at least as large as the source disk.

1. Get the media

1. Open Backup → Recovery Bootstrap. The Boot media list shows the current release’s breeze-recovery-linux-amd64.iso and breeze-recovery-linux-arm64.iso with their SHA-256 checksums. The same files are attached to each GitHub release and served by your Breeze server at /download/recovery-iso/linux/<arch>.
2. Write the ISO to a USB stick (dd if=breeze-recovery-linux-amd64.iso of=/dev/sdX bs=4M status=progress, Rufus in DD mode, or balenaEtcher), or attach it as a virtual DVD to a VM.
3. Keep the media current. The server enforces a minimum media version at code exchange, so an ISO from an older release is refused with This recovery media (vX) is older than the server requires (vY); download the current ISO.

The media is a Debian live system with the breeze-backup binary and nothing else of yours on it: no server address, no credentials, no snapshot data. Everything is fetched at recovery time with the code.

2. Create a recovery code

1. Still on Recovery Bootstrap, in the Bare-metal recovery panel, pick the snapshot to rebuild from. Only snapshots marked Bare-metal restorable are listed.
2. Choose the Device identity:
   • Original device — the rebuilt machine keeps its machine ID, hostname and agent enrollment, and the recovery completes when it checks in for the first time. Use this to bring the same device back on repaired or identical hardware.
   • New device — the machine ID is regenerated, the hostname gets a -restored suffix and the agent identity is stripped, so it enrolls as a brand-new device if you install an agent. Use this for rehearsals, VMs, or when the original is still in service.
3. Click Create recovery code. The code (XXX-XXX-XXX) is shown once, expires after 15 minutes, and can be used once. Create it right before you boot the media.

Note

One recovery at a time per device. While a recovery is anywhere between created and rebooted, creating another for the same device is refused with recovery_in_progress; it clears once the recovery reaches a terminal state (checked_in, completed, failed or refused).

Note

Recovery media too old. If this snapshot’s files reference objects stored under an earlier snapshot, the console needs recovery media that supports cross-snapshot references. An older ISO is refused with a message telling you to download the current recovery media and boot again — the target disk is never touched.

Note

Preparing file index. The first time you recover from an incremental snapshot, Breeze may need a few seconds to a few minutes to verify which older-snapshot objects it references. The console retries automatically and shows “Breeze is preparing the file index for this snapshot…” while it waits — this is expected and does not consume one of your three code attempts.

3. Boot and follow the console

1. Boot the target machine from the media. GRUB starts the live system automatically after 5 seconds; the console also mirrors to the first serial port (ttyS0, 115200 8N1) for headless servers reached over IPMI or SOL.
2. Breeze server URL — enter your server’s https:// address. Plain http:// is refused unless the media was booted with breeze.insecure=1 on the kernel command line (development only).
3. Recovery code — enter the code. You get three attempts. On success the console downloads the plan: the device, snapshot time, source disk layout, the detected target disk with model, size and serial, and the identity mode.
4. If more than one candidate disk is found, choose one by number. Disks that are mounted or hold the live system are never offered.
5. Confirm by typing the target disk’s serial number exactly as shown, or ERASE when the disk reports no serial (common for virtual disks). Anything else cancels without touching the disk.
6. The seven rebuild phases run with progress on screen: preflight, provision, restore, boot, identity, encryption, validate. Each phase is also posted to Breeze, so the recovery’s timeline on the Recovery Bootstrap panel moves through Media booted → Planned → Restoring → Validated → Rebooted.
7. Restored. Rebooting in 10 s (press any key to stay). Remove the media. With Original device the recovery becomes Checked in on the restored agent’s first heartbeat; with New device it is Completed as soon as validation passes.

If a phase fails or the snapshot is refused, the reason stays on screen with a [r]etry [s]hell [p]oweroff prompt, and the same reason is recorded on the recovery in Breeze. [s]hell drops to a root shell on the live system for inspection. Re-running the same recovery resumes: phases already completed are skipped and restore progress is kept.

Unattended boot options

The kernel command line accepts breeze.server=, breeze.code=, breeze.target=, breeze.confirm= and breeze.after=poweroff to pre-answer the prompts. These exist for Breeze’s own CI and for lab automation; a code on a command line is a code in a boot log, so do not use them for production recoveries.

Known limits of the media path

• Linux only today. There is no Windows or macOS recovery media. For those, use reinstall-then-recover, or rebuild a Windows snapshot onto a VHDX with Restore as VM or a DR rehearsal.
• One blank UEFI/GPT disk at least as large as the source disk, from a snapshot marked Bare-metal restorable. Multi-disk, BIOS/MBR, LVM, LUKS, RAID, btrfs and ZFS layouts are named at backup time and not rebuilt.
• No driver injection. The rebuilt system boots with the drivers its own image carries; see Windows fidelity for the Windows side.
• Rehearsal is not production. DR rehearsals and Restore as VM rebuild into a disk image on a rebuild host and prove the snapshot can be rebuilt; only a recovery from the media brings a real machine back (with Original device it counts as done once the machine checks in).

Every rebuild outcome, with its measured duration, also feeds the device’s recovery readiness — a failed or stale rebuild shows up as a risk factor on the Verification tab.

---

Alternative: recover into a freshly installed OS

Use this mode on Windows and macOS, on Linux machines whose layout is not bare-metal restorable, or when you only need data or configuration back on a machine that already boots.

1. Get a working OS onto the target machine by installing one normally.
2. Generate a recovery token from a backup snapshot and download the recovery bundle (the breeze-backup binary, a launch script, and bootstrap.json).
3. On the target machine, run the recovery binary with the token — no Breeze enrollment needed.
4. It downloads the snapshot: for a file snapshot, files are restored to their original paths; for a system_image snapshot, every OS-state artifact is downloaded, its size and SHA-256 checksum are verified against the snapshot’s manifest, and the platform restorer applies it.
5. A post-restore validation probe runs and reports pass/fail; nothing reboots the machine for you.

Generating a Recovery Token

1. Find the snapshot you want to recover from (via the Backup dashboard or device backup tab).
2. Select Bare Metal Recovery from the restore options.
3. Configure the recovery:
   • Snapshot — the single backup to recover from (one snapshot per token)
   • Token lifetime — how long the token remains valid, 1–168 hours
   • Restore type — Full, Selective, or Bare Metal
   • Target configuration — optional source=target path remappings applied on the recovery machine
4. Click Generate Token.
5. The token is displayed once. Copy it immediately — it’s stored as a SHA-256 hash and cannot be retrieved later.

Once a token exists, download the recovery bundle (the helper binary and a launch script) for the target platform from the Recovery Bootstrap tab. Bootable media is no longer built per token; use the release ISO described above.

Recovery bundle signing

v0.118.0+. Before it runs the helper binary, a recovery bundle’s launch script downloads that binary’s signature from your Breeze server (authenticated with the recovery token) and checks it with minisign. It checks against the public key written into the bundle when it was built, never a key fetched at run time. The script refuses to run the helper when:

• the bundle was built without recovery signing configured on the server, so it carries no key;
• minisign (or, on Linux and macOS, curl) is not installed on the recovery machine;
• the server has no signature for the binary, or the signature does not match.

To build bundles that run, set RECOVERY_SIGNING_PRIVATE_KEY and RECOVERY_SIGNING_PUBLIC_KEY on the API, and make a minisign binary available to it (see Environment Variables → Backup). Rebuild bundles you downloaded before upgrading to v0.118.0, and install minisign on the machine you recover.

Danger

Recovery tokens are shown only once at creation time. Store the token securely and use it promptly. If lost, generate a new one.

Note

Recovering data and OS state for one machine takes two tokens and two runs unless the snapshot came from a profile with both Files and System image enabled: one against the device’s system_image snapshot, one against its file snapshot.

---

Running the Recovery

1. Get the target machine to a booted OS by installing one normally.
2. Install minisign (and curl on Linux and macOS) on the target machine; the launch script needs it to verify the helper. Download and extract the recovery bundle for the target platform/architecture, then run the launch script (run-recovery.sh / run-recovery.ps1) or the binary directly:

   breeze-backup bmr-recover --token <recovery-token> --server <breeze-server-url>

   Add --target-path <source>=<target> (repeatable) to remap individual file paths from the snapshot onto different locations on the recovery machine; anything not remapped restores to its original path. Ctrl+C (SIGINT/SIGTERM) stops the run cleanly and reports recovery interrupted by signal.
3. The recovery agent authenticates with the token and downloads the snapshot manifest.
4. For a system_image snapshot, the recovery binary downloads the system-state manifest and each artifact into a temporary staging directory, verifies every artifact’s size and checksum, and then applies them — see What a system_image recovery applies. Any artifact that fails verification is discarded and reported as a warning, and the run’s stateApplied result is false.
5. For a file snapshot, files are downloaded and written to their original paths (or their --target-path remapping). Files, symbolic links, empty directories, ownership and permission bits are restored when the snapshot recorded them (see File backup fidelity); ownership and setuid/setgid/sticky bits are applied only when the recovery runs as root, otherwise one summary warning is printed.
6. A post-restore validation probe checks network reachability, presence of critical files, and service status, and reports the result — it does not repair or retry anything it finds wrong.

Reading the result

The run ends with a status and a short result summary (filesRestored, failedFiles, bytesRestored, stateApplied, validated, warnings, and an optional result code). The same fields are recorded against the recovery in Breeze, and the Recovery Bootstrap tab shows any code as Result code: … — for example an integrity code such as checksum_mismatch (see Integrity checks on restore). Advisory warnings (unattested snapshot, vault fallback, files-only Windows recovery) are shown as warnings, never as the failure reason.

For an attested snapshot, the recovery checks the manifest, the system-state manifest and every file against the attestation before using them, and stages each file privately (readable only by root, or SYSTEM and Administrators) before moving it into place, keeping the replaced file’s owner, mode and permissions. A snapshot that failed its integrity check is refused.

Status	Meaning
completed	Every file restored and, for a system_image snapshot, the system state was found, verified and applied (stateApplied: true).
partial	Some files restored or the state was applied, but something else failed — read warnings. A system_image run whose state manifest was found but could not be applied (missing required step, failed checksum) is never reported as completed.
failed	Nothing was restored. Also the outcome when the token’s snapshot advertised system state that could not be found, or a step the snapshot marks as required was never collected.

A snapshot counts as advertising system state when its backup type is system_image or it recorded a state manifest — so a system_image snapshot whose state collection failed is held to the same rule rather than recovering “successfully” with files only. The same gate applies to breeze-backup rebuild and the recovery media, which refuse such a snapshot before touching the disk.

Before v0.112.0, a completed system_image recovery applied nothing

Snapshots taken before v0.112.0 published their OS-state artifacts under a location the recovery binary never looked at, so a system_image recovery downloaded them, applied nothing and still reported completed with stateApplied: false. Both halves are fixed in v0.112.0 — the agent publishes state where the consumer reads it, and the consumer refuses to report completed when advertised state was not applied — but only for snapshots taken by a v0.112.0 or later agent. To recover OS state, take a fresh system_image backup after upgrading.

---

What a system_image recovery applies

The artifacts are collected by the agent at backup time and applied by the platform restorer on the booted OS. Steps run in order; a failing step is logged and the remaining steps still run.

Linux

Step	What is applied
/etc	Copied onto the live /etc — regular files, symlinks, modes and timestamps. Excluded, so the booted OS keeps its own identity and networking: fstab, machine-id, hostname, netplan/, network/interfaces, NetworkManager/system-connections/. The skipped paths are logged.
Packages	The captured package list is reinstalled — dpkg --set-selections + apt-get dselect-upgrade on Debian/Ubuntu, dnf install on RHEL-family. Needs working package repositories. Entries are validated first: on RHEL-family an invalid package name is skipped with a warning; on Debian/Ubuntu a selections list with any invalid line is not applied at all, with a warning.
Services	Every unit the source machine had enabled is re-enabled with systemctl enable.
Firewall	iptables-restore of the captured rules.
Scheduled tasks	Per-user crontabs are reinstalled with crontab -u <user>. The system /etc/crontab is deliberately left alone.

Note

Permissions and ownership inside the restored /etc currently reflect the staging copy (0600/0700, root-owned), not the source machine. Review anything that must be world-readable (for example /etc/hosts, /etc/ssl/certs) after a Linux recovery.

Windows — v0.120.0+: bmr-recover on Windows restores files only. It no longer imports registry hives, the BCD store, certificates, firewall policy or drivers into the running system. The result carries stateApplied: false, the code system_state_requires_rebuild and a warning saying so; this is not a failure, and the Recovery Bootstrap tab shows the note System state is applied by a bare-metal rebuild. To apply a Windows snapshot’s system state, rebuild it with the rebuild engine instead — for example Restore as VM — which applies the hives, boot configuration and the rest offline.

Earlier agents imported the SYSTEM, SOFTWARE, SAM and SECURITY hives with reg restore, the BCD store with bcdedit /import, the certificate store with certutil -restoreDB, firewall policy with netsh advfirewall import, and staged captured driver packages with pnputil /add-driver … /install, each best-effort.

Since v0.120.0 the Windows agent flushes the loaded registry hives to disk just before it takes the VSS snapshot for a system-state backup, so registry changes made shortly before the backup (a newly created service, for example) are included. Earlier backups could miss changes that were still only in memory.

macOS — preference plists into /Library/Preferences, LaunchDaemon/LaunchAgent items into /Library/LaunchDaemons and /Library/LaunchAgents, and the network configuration into SystemConfiguration/preferences.plist (followed by a configd restart). Best-effort, warnings only.

On macOS the apply steps never fail the run, so a stateApplied: false there always means an artifact failed download or verification — check warnings for which one. On Windows, stateApplied: false is expected from v0.120.0 on (files only, see above).

---

What a Recovered Machine Is — and Isn’t

A machine recovered with a file snapshot is: the OS you installed or booted, plus the recovered files, otherwise unchanged. A machine recovered with a system_image snapshot on Linux or macOS is: the OS you installed or booted, with the source machine’s configuration layered back on top — its registry hives or /etc, services, firewall rules, scheduled tasks and (Linux) package set — while keeping the booted OS’s own disk layout, boot identity, hostname, machine ID and network configuration. Neither snapshot type produces a byte-identical clone of the original machine: bmr-recover does no disk or partition imaging, and kernel and driver binaries come from the OS you installed. For a from-scratch rebuild of a Linux disk, use breeze-backup rebuild instead.

---

Is the snapshot bare-metal restorable?

Every system_image backup taken by a v0.112.0 or later agent on Linux or Windows also records the machine’s disk layout (disks, partition table, filesystems, boot mode, fstab) alongside the snapshot, and Breeze assesses whether that layout is one the rebuild engine can reproduce. The verdict is shown in the Snapshot Browser header as a Bare-metal restorable or Not bare-metal restorable badge — hover the amber badge for the reasons — and is included as a warning on the backup run.

A layout is restorable when the machine boots UEFI, its OS lives on one GPT disk with an EFI system partition, and the root filesystem is ext4, xfs or ntfs. Anything else is named at backup time rather than discovered at recovery time:

• BIOS/MBR boot (only UEFI with GPT is supported)
• the OS tree spread across more than one disk
• LVM volumes, LUKS/dm-crypt encrypted volumes, software RAID members
• a btrfs root filesystem, or ZFS anywhere in the OS tree
• no disk layout captured at all (macOS backups, or a collection error)

The badge governs only the rebuild path below. A snapshot marked not restorable can still be used with bmr-recover onto an OS you install yourself.

---

Rebuilding a Linux disk from scratch (breeze-backup rebuild)

breeze-backup rebuild is the from-scratch counterpart to bmr-recover: instead of restoring onto an OS you installed, it takes a blank disk (or a raw image file), provisions the partitions recorded in the snapshot’s layout manifest, restores a whole-machine snapshot into them, applies the system state offline, installs a bootloader and validates the result. It ships in the same breeze-backup binary as the recovery bundle, and — as of this release — runs on Windows rebuild hosts too: a Windows snapshot rebuilds on a Windows host, a Linux snapshot on a Linux host. The steps below (partition provisioning, offline restore, bootloader install) apply to both; where a step is platform-specific, that’s called out.

Scope

Run from a booted host matching the snapshot’s platform — a Linux snapshot rebuilds on Linux, a Windows snapshot on Windows (Breeze checks this and refuses the pair otherwise); the snapshot must be marked Bare-metal restorable and the target must be UEFI/GPT. The recovery media runs it for you; the command below is for scripted or unusual recoveries and does not appear in the device’s command history. Restore as VM and DR bare-metal rebuild steps also run this engine, targeting a VHDX image instead of a disk.

breeze-backup rebuild \
  --snapshot <snapshot-id> \
  --target disk:/dev/sdb        # or image:/path/to/disk.img with --image-size 40G
  --provider-config provider.json \
  [--identity original|new] [--marker-file marker.json] \
  [--dry-run] [--result-json result.json]

Flag	Purpose
--snapshot	The system_image snapshot to rebuild from (must carry a layout manifest).
--target	disk:/dev/… for a real block device, image:/path.img for a raw image file (created sparse; --image-size is required when the file does not exist yet), or vhdx:<path> for a VHDX disk image. A mounted disk, or the one backing the running system, is refused. On a live Windows host, only vhdx: is supported — disk: needs a WinPE-booted environment, which doesn’t ship until the Windows recovery media (W07).
--provider-config	JSON file with the backup destination credentials, as used by the recovery bundle.
--identity	original (default) keeps the machine ID, hostname and agent enrollment and writes a recovery marker; new clears the machine ID, appends -restored to the hostname and strips the agent’s device identity so it re-enrolls as a new device.
--dry-run	Run the preflight only — fetch and verify the layout, plan the partitions, check the target — and print the plan without writing anything.
--state-dir	Where the resumable state file lives (default /var/lib/breeze/rebuild).
--force-reprovision, --allow-partial, --no-initramfs	Re-partition even if a previous run already did; continue when some files failed to restore; skip the initramfs regeneration.
--expect-system-state	auto (default), true or false: whether the snapshot must carry system state that the rebuild applies. auto says yes for a system_image snapshot (the recovery media and --token mode take this from the server’s bootstrap; --provider-config mode infers it from a layout.json or state manifest in the snapshot). false rebuilds a file-only snapshot with a warning.

The rebuild runs seven phases in order — preflight → provision → restore → boot → identity → encryption → validate:

1. Preflight downloads layout.json, refuses a snapshot that is not restorable or whose platform doesn’t match the rebuild host’s, checks the target is safe and large enough, plans the partitions, and downloads and checksum-verifies the snapshot and system-state manifests. Nothing is written. A system_image snapshot whose system-state/manifest.json is missing (or lists no artifacts) is refused here — the rebuild never proceeds files-only when system state was expected.
2. Provision wipes the target, recreates the GPT partitions with their original type codes, GUIDs, names and filesystem UUIDs/labels, and formats them.
3. Restore mounts the new partitions, restores the file snapshot into them, then applies the system state offline into that tree. On Linux, unlike a live bmr-recover, /etc is restored without the identity/network excludes (fstab, machine-id, hostname and network configuration do land, because the rebuilt disk is the original machine), services are enabled with systemctl --root, crontabs are written straight into the spool, and firewall rules are written to /etc/iptables/rules.v4 (or /etc/breeze/recovery/iptables.rules with a warning if iptables-persistent is absent); package reinstall is skipped offline. On Windows, registry hives, the certificate store and firewall policy are applied offline into the mounted tree — see Windows fidelity below for exactly what that covers.
4. Boot installs GRUB for UEFI on Linux (Debian/Ubuntu via grub-install + update-grub, RHEL-family via grub2-mkconfig + efibootmgr), regenerates the initramfs, and always writes the removable-media fallback loader (EFI/BOOT/BOOTX64.EFI / BOOTAA64.EFI); other Linux distribution families are not supported. On Windows, bcdboot regenerates the EFI system partition, run as the rebuild host’s own System32 binary, resolved by absolute path, never anything from the restored tree. Driver injection is not supported yet — see Windows fidelity.
5. Identity applies the --identity choice.
6. Encryption is a no-op in this release — encrypted layouts are refused at preflight, and a BitLocker-protected Windows source restores in plaintext with a recorded re-encryption intent (see Windows fidelity).
7. Validate spot-checks a sample of restored files against their checksums, confirms the bootloader (grub.cfg on Linux, the BCD store on Windows) exists, cross-checks filesystem UUIDs/volume identifiers against the new partitions, then syncs and unmounts. When system state was expected, it also fails with system state not applied if the restore phase did not apply it.

The result JSON carries stateManifestFound and stateApplied alongside status; a rebuild is never completed unless stateApplied is true whenever system state was expected.

Progress is checkpointed to <state-dir>/rebuild-<snapshot>-<target>.json after every phase. If a run is interrupted, re-running the same command resumes: phases already completed are skipped, the partitions are re-attached rather than re-created, and the state file is removed only on success.

---

Restore as VM

The VM Restore Wizard’s Rebuild engine option runs the same rebuild engine described above, but writes the result straight to a VHDX disk image instead of a physical disk on a platform-matched rebuild host. On a Windows rebuild host it can also create (but does not start) a Hyper-V VM from that VHDX — only when you ask for one in step 6; otherwise, and always on Linux, you attach the VHDX to a VM yourself. It’s offered alongside Full Restore and Instant Boot whenever the selected snapshot carries a layout manifest (the same Bare-metal restorable snapshots the recovery media uses).

1. Open the restore workflow for the device and choose Restore as VM.
2. Select the backup snapshot to restore.
3. On the Restore mode step, choose Rebuild engine.
4. Pick a rebuild host running the same platform as the snapshot — an online device running the Breeze helper with enough free disk space for the image. On Linux the host also needs qemu-utils; the engine’s preflight refuses the run if qemu-img is missing or the free space is short. A Windows host writes the VHDX natively, so the rebuild itself needs no Hyper-V role — only the optional VM in step 6 does, and without it that step fails as described there.
5. Enter an absolute output path on the rebuild host ending in .vhdx (a POSIX path on Linux, a drive-letter path on Windows — a path in the other host’s style is refused with output_path_host_mismatch).
6. On a Windows rebuild host, optionally name a Hyper-V VM and virtual switch — Breeze creates a Generation 2 VM from the finished VHDX, with no network adapter unless you name a switch, and leaves it off for you to start. If VM creation fails, the rebuild still completes, the VHDX is kept, and the failure is reported rather than hidden: it is the first warning on the restore job (shown as its error summary in the restore history) and is recorded on the recovery’s result as vmCreated: false with the reason in vmError.
7. Click Start Rebuild.

The rebuilt image always gets a new machine identity — a new machine ID, a -restored hostname, and no agent enrollment — since it’s building a standalone copy, not reclaiming the original device.

---

Windows fidelity

What a Windows whole-machine rebuild preserves, and what it doesn’t yet:

Preserved:

• NTFS security descriptors (owner, group, DACL) for every file and directory, so a rebuilt C:\Windows\System32\config keeps its original ACLs rather than inheriting Authenticated-Users-Modify from a fresh volume — this closes the class of issue behind CVE-2021-36934.
• Partition GUIDs, the EFI boot configuration, and (best-effort) boot-start storage driver settings for the disk controller the target machine actually has.
• The machine’s SID is never regenerated.

Not yet restored:

• Driver injection is not supported yet: the rebuilt system boots with the drivers its own image carries. Boot the restored machine and install any other drivers from Windows. breeze-backup rebuild --drivers is refused with that message rather than ignored.
• Hard links, alternate data streams, and EFS-encrypted file contents.
• Windows Recovery Environment (WinRE) partition contents — the partition is recreated and formatted but left empty; reagentc is not run.
• A BitLocker-protected source volume restores in plaintext. Breeze records the intent to re-encrypt on first boot; the executor for that intent ships with the Windows recovery media (W07).
• A domain controller source is refused at preflight — recovering a DC this way risks a broken AD replication topology; use your normal DC recovery procedure instead. The refusal can only be overridden from the command line (breeze-backup rebuild --allow-domain-controller), after reading the DC recovery guidance; the recovery console, Restore as VM and DR rehearsals never override it.

---

When to Use BMR

Scenario	Approach
Hard drive failure (Linux, UEFI/GPT)	Boot the Breeze recovery media and enter a recovery code for a Bare-metal restorable whole-machine snapshot.
Hard drive failure (other)	Install/boot an OS on the new disk, recover data with a file snapshot, then apply configuration with a system_image snapshot.
Machine replacement	Install a base OS on the replacement hardware, then recover data and system state with BMR. Drivers and hardware-specific configuration come from the OS you installed; rebuild targets identical or compatible hardware.
Disaster recovery	BMR as part of a DR plan.
Migration	Recover data onto different hardware, then decide whether to apply the system_image snapshot — it brings the old machine’s services, firewall rules and (Linux) package set with it.

For recovering individual files or databases onto an already-enrolled device, use the standard restore workflow instead — it’s faster and doesn’t require a recovery token.

---

Recovery Token Security

• Tokens authenticate recovery agents the same way JWT authenticates regular users — they grant time-limited access to a specific snapshot
• Tokens are hashed (SHA-256) at rest and cannot be retrieved after creation
• Each token is scoped to a single snapshot and organization
• Expired tokens are automatically invalidated
• A token is consumed by the first recovery that completes (fully or with some files failed). A run that fails before completing — for example a network drop mid-download — is recorded against the token but does not consume it, so you can rerun bmr-recover with the same token until it expires. Revoke the token from the console if you no longer want it usable.