Restore Options - Polystack Documentation

Overview

Ironcore Backup Solution (IBS) offers three restore paths depending on the recovery scenario:

VM-Level Restore brings back a full virtual machine, optionally on a new host and with a new name.
Live-Restore registers and powers on the VM in seconds — the remaining blocks stream on demand while the OS is running.
File-Level Restore opens a snapshot in a read-only browser and recovers individual files or directories.

Prerequisites

An active Polystack account with project membership
At least one snapshot available in a datastore your project can read
For VM restore, a target compute host with adequate resources

Compare Restore Methods

Method	Use When	Time to Available	Restored Object
Live-Restore	Need the VM running in seconds	Seconds	A running VM, restore continues in background
VM-Level Restore	Recovering after deletion / corruption	Minutes-hours	A new VM, fully restored before power-on
File-Level Restore	A few files need recovering	Seconds	Files / directories / a downloadable archive

Live-Restore a VM

Live-restore powers on the VM the moment the snapshot manifest is read. Blocks are pulled from the datastore on demand as the guest OS accesses them.

Dashboard
CLI

Open the snapshot

Navigate to Backup Solution > Snapshots and open the snapshot you want to restore.

Click Live-Restore

On the snapshot detail page, click Live-Restore.

Choose the target host

Select the Target host from the dropdown. The Dashboard filters for compute hosts that have enough RAM and disk headroom.

Choose target storage

Select the Target storage backend for the new VM disk.

Optionally rename

Provide a new VM name and ID if the original is still present.

Start the restore

Click Start. The Dashboard shows two progress bars — guest availability and background restore.

VM transitions to Running within seconds. Background restore continues to completion.

Live-restore a VM

ironcore-backup vm restore \
  --snapshot ibs-primary:vm/12345/2026-05-21T00:00:00Z \
  --target-host compute-07 \
  --storage hot-ssd \
  --rename vm-12345-restored \
  --live

CLI prints TASK OK (VM running) when the guest is available. Background restore continues — track with task list.

Live-restore is the fastest recovery path for any sufficiently large VM. For very small VMs (under a few GB), a standard VM restore may finish in comparable wall-clock time.

Standard VM-Level Restore

A full restore reconstructs every block before powering the VM on. Use this when you want the new VM to start from a fully-resident disk image.

Dashboard
CLI

Open the snapshot

Navigate to the snapshot in Backup Solution > Snapshots.

Click Restore VM

On the snapshot detail page, click Restore VM.

Set restore options

Pick the target host, storage backend, and a new VM name or ID. Leave Live unchecked.

Start the restore

Click Start.

VM transitions to Stopped when restore completes. Power on manually when ready.

Standard VM-level restore

ironcore-backup vm restore \
  --snapshot ibs-primary:vm/12345/2026-05-21T00:00:00Z \
  --target-host compute-07 \
  --storage hot-ssd \
  --rename vm-12345-restored

File-Level Restore

Recover a single file, directory, or archive without restoring the full VM.

Dashboard
CLI

Open the snapshot file browser

Open the snapshot and click File Browser.

Navigate to the path

Browse the directory tree or use the search bar to find a file by name or content.

Select and download

Select one or more files. Click Download to receive the selection as a ZIP, a Zstandard-compressed tarball, or a single file.

The browser begins streaming the requested files.

Restore a single file

ironcore-backup file restore \
  --snapshot ibs-primary:vm/12345/2026-05-21T00:00:00Z \
  --path /var/www/html/index.php \
  --target /tmp/restore/

Restore a directory as Zstandard archive

ironcore-backup file restore \
  --snapshot ibs-primary:vm/12345/2026-05-21T00:00:00Z \
  --path /etc \
  --format tar.zst \
  --target /tmp/etc-2026-05-21.tar.zst

Open an interactive recovery shell

ironcore-backup file shell \
  --snapshot ibs-primary:vm/12345/2026-05-21T00:00:00Z

The file browser opens the snapshot read-only and decrypts chunks on demand. Original metadata (owner, permissions, modification time) is preserved in every download format.

Container Restore

Dashboard
CLI

Open the snapshot

Open the container snapshot in Backup Solution > Snapshots.

Click Restore Container

On the snapshot detail page, click Restore Container.

Set target options

Pick the target host and storage backend. Optionally rename the container.

Start the restore

Click Start.

The container is restored with the original filesystem state.

Restore a container

ironcore-backup container restore \
  --snapshot ibs-primary:container/200/2026-05-21T00:00:00Z \
  --target-host compute-04 \
  --storage hot-ssd

Host File Restore

Restore one or more files from a physical host backup back to the host or to a different machine.

Restore /etc/nginx from a host backup to a different machine

ironcore-backup file restore \
  --snapshot ibs-primary:host/web-01-srv/2026-05-21T00:00:00Z \
  --path /etc/nginx \
  --target /var/restore/nginx-web-01

Restore Time Estimates

These ranges are typical for a modern 10 GbE network with healthy datastores. Actual times vary with deduplication hit rate, network throughput, and target storage speed.

Operation	50 GB VM	500 GB VM	5 TB VM
Live-Restore — time to running	< 5 s	< 5 s	< 10 s
Full VM restore	1-3 min	8-20 min	1.5-3 h
Single 100 MB file	< 5 s	< 5 s	< 10 s
10 GB directory as archive	30-60 s	30-90 s	30-120 s

Troubleshooting

Live-Restore is slow despite high network capacity

Check whether the target storage backend is healthy and not saturated. Also confirm the workload running on the guest is not generating heavy random IO — live-restore prioritises guest IO requests over background restore.

File browser fails with `decryption error`

The snapshot was created with an encryption key your project does not have access to. Contact the backup administrator to grant access to the key or to provide a paperkey-restored credential.

Restored VM does not boot

Boot order, virtio drivers, or storage backend differences between the source and target hosts can prevent first boot. Open the VM console and inspect the boot loader. Re-attach the original storage type if mismatched.

`destination not writable`

The target host or storage is full or read-only. Free space or change the target storage backend.

Next Steps

Monitoring Jobs

Track running restore tasks and review history

Verification and Validation

Verify backups before relying on them in a restore scenario

Troubleshooting

Diagnose restore errors and unexpected behaviour

How It Works

Conceptual overview of the restore pipeline

​Overview

​Compare Restore Methods

​Live-Restore a VM

Open the snapshot

Click Live-Restore

Choose the target host

Choose target storage

Optionally rename

Start the restore

​Standard VM-Level Restore

Open the snapshot

Click Restore VM

Set restore options

Start the restore

​File-Level Restore

Open the snapshot file browser

Navigate to the path

Select and download

​Container Restore

Open the snapshot

Click Restore Container

Set target options

Start the restore

​Host File Restore

​Restore Time Estimates

​Troubleshooting

​Next Steps

Monitoring Jobs

Verification and Validation

Troubleshooting

How It Works

Overview

Compare Restore Methods

Live-Restore a VM

Standard VM-Level Restore

File-Level Restore

Container Restore

Host File Restore

Restore Time Estimates

Troubleshooting

Next Steps