> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polystack.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Restore Options

> Restore full VMs with live-restore, recover individual files, or rehydrate containers and hosts from Ironcore Backup Solution snapshots.

## 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.

<Note>
  **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
</Note>

***

## 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.

<Tabs>
  <Tab title="Dashboard" icon="gauge">
    <Steps titleSize="h3">
      <Step title="Open the snapshot" icon="search">
        Navigate to **Backup Solution** > **Snapshots** and open the snapshot
        you want to restore.
      </Step>

      <Step title="Click Live-Restore" icon="play">
        On the snapshot detail page, click **Live-Restore**.
      </Step>

      <Step title="Choose the target host" icon="server">
        Select the **Target host** from the dropdown. The Dashboard filters for
        compute hosts that have enough RAM and disk headroom.
      </Step>

      <Step title="Choose target storage" icon="hard-drive">
        Select the **Target storage** backend for the new VM disk.
      </Step>

      <Step title="Optionally rename" icon="tag">
        Provide a new VM name and ID if the original is still present.
      </Step>

      <Step title="Start the restore" icon="play">
        Click **Start**. The Dashboard shows two progress bars — guest
        availability and background restore.

        <Check>VM transitions to **Running** within seconds. Background restore continues to completion.</Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="Live-restore a VM" theme={null}
    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
    ```

    <Check>CLI prints `TASK OK (VM running)` when the guest is available. Background restore continues — track with `task list`.</Check>
  </Tab>
</Tabs>

<Tip>
  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.
</Tip>

***

## 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.

<Tabs>
  <Tab title="Dashboard" icon="gauge">
    <Steps titleSize="h3">
      <Step title="Open the snapshot" icon="search">
        Navigate to the snapshot in **Backup Solution** > **Snapshots**.
      </Step>

      <Step title="Click Restore VM" icon="rotate-ccw">
        On the snapshot detail page, click **Restore VM**.
      </Step>

      <Step title="Set restore options" icon="settings">
        Pick the target host, storage backend, and a new VM name or ID. Leave
        **Live** unchecked.
      </Step>

      <Step title="Start the restore" icon="play">
        Click **Start**.

        <Check>VM transitions to **Stopped** when restore completes. Power on manually when ready.</Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="Standard VM-level restore" theme={null}
    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
    ```
  </Tab>
</Tabs>

***

## File-Level Restore

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

<Tabs>
  <Tab title="Dashboard" icon="gauge">
    <Steps titleSize="h3">
      <Step title="Open the snapshot file browser" icon="folder-search">
        Open the snapshot and click **File Browser**.
      </Step>

      <Step title="Navigate to the path" icon="folder">
        Browse the directory tree or use the search bar to find a file by name
        or content.
      </Step>

      <Step title="Select and download" icon="download">
        Select one or more files. Click **Download** to receive the selection
        as a ZIP, a Zstandard-compressed tarball, or a single file.

        <Check>The browser begins streaming the requested files.</Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="Restore a single file" theme={null}
    ironcore-backup file restore \
      --snapshot ibs-primary:vm/12345/2026-05-21T00:00:00Z \
      --path /var/www/html/index.php \
      --target /tmp/restore/
    ```

    ```bash title="Restore a directory as Zstandard archive" theme={null}
    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
    ```

    ```bash title="Open an interactive recovery shell" theme={null}
    ironcore-backup file shell \
      --snapshot ibs-primary:vm/12345/2026-05-21T00:00:00Z
    ```
  </Tab>
</Tabs>

<Info>
  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.
</Info>

***

## Container Restore

<Tabs>
  <Tab title="Dashboard" icon="gauge">
    <Steps titleSize="h3">
      <Step title="Open the snapshot" icon="search">
        Open the container snapshot in **Backup Solution** > **Snapshots**.
      </Step>

      <Step title="Click Restore Container" icon="rotate-ccw">
        On the snapshot detail page, click **Restore Container**.
      </Step>

      <Step title="Set target options" icon="settings">
        Pick the target host and storage backend. Optionally rename the container.
      </Step>

      <Step title="Start the restore" icon="play">
        Click **Start**.

        <Check>The container is restored with the original filesystem state.</Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="Restore a container" theme={null}
    ironcore-backup container restore \
      --snapshot ibs-primary:container/200/2026-05-21T00:00:00Z \
      --target-host compute-04 \
      --storage hot-ssd
    ```
  </Tab>
</Tabs>

***

## Host File Restore

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

```bash title="Restore /etc/nginx from a host backup to a different machine" theme={null}
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

<AccordionGroup>
  <Accordion title="Live-Restore is slow despite high network capacity" icon="gauge">
    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.
  </Accordion>

  <Accordion title="File browser fails with `decryption error`" icon="lock">
    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.
  </Accordion>

  <Accordion title="Restored VM does not boot" icon="alert-triangle">
    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.
  </Accordion>

  <Accordion title="`destination not writable`" icon="hard-drive">
    The target host or storage is full or read-only. Free space or change the
    target storage backend.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Monitoring Jobs" icon="activity" href="/services/ironcore-backup/user-guide/monitoring-jobs" color="#bf9667">
    Track running restore tasks and review history
  </Card>

  <Card title="Verification and Validation" icon="check" href="/services/ironcore-backup/admin-guide/verification-validation" color="#bf9667">
    Verify backups before relying on them in a restore scenario
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/services/ironcore-backup/user-guide/troubleshooting" color="#bf9667">
    Diagnose restore errors and unexpected behaviour
  </Card>

  <Card title="How It Works" icon="info" href="/services/ironcore-backup/user-guide/how-it-works" color="#bf9667">
    Conceptual overview of the restore pipeline
  </Card>
</CardGroup>