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

# How Ironcore Backup Works

> Understand block-level change tracking, client-side encryption, deduplication, and the full backup-to-restore data flow inside Ironcore Backup Solution.

## Overview

Ironcore Backup Solution (IBS) protects workloads using **block-level change tracking**,
**content-defined deduplication**, **Zstandard compression**, and **client-side encryption**.
Every backup transmits only the modified blocks since the previous run, encrypts them on
the client before they leave the workload, and writes them into a chunk-addressable
datastore that deduplicates identical blocks across every protected source.

This page explains the end-to-end flow from a running workload to a restorable snapshot.

<Note>
  **Prerequisites**

  * An active Polystack account with project membership
  * At least one backup datastore configured by an administrator
  * The workload you want to protect is reachable from a backup client
</Note>

***

## Deployment Model

Ironcore Backup Solution (IBS) uses **two complementary deployment models**
depending on the workload type:

<CardGroup cols={2}>
  <Card title="Agentless (for VMs and containers)" icon="server" color="#bf9667">
    For virtual machines and system containers running on the Ironcore platform,
    backup is fully agentless from the workload's perspective. The hypervisor
    performs block-level change tracking, reads only modified blocks, and
    streams them to the backup datastore. **No software is installed inside
    the guest VM or container.** The guest is unaware of the backup.
  </Card>

  <Card title="Agent-based (for physical hosts)" icon="hard-drive" color="#bf9667">
    For physical Linux hosts and any standalone workload outside the
    virtualisation layer, you install the lightweight `ironcore-backup-client`
    package on the host. The client reads files directly, applies the same
    pipeline (chunk, compress, encrypt), and pushes to the datastore. Best
    for configuration, application data, and bare-metal protection.
  </Card>
</CardGroup>

<Info>
  The same pipeline (change tracking, chunking, compression, encryption) runs
  in both models. Only the **location** of the pipeline differs: the hypervisor
  for VM and container backups, the host itself for physical machines.
</Info>

***

## Backup Pipeline

```mermaid theme={null}
graph LR
    A[Running Workload] -->|Block-level CBT| B[Identify changed blocks]
    B -->|Content-defined chunking| C[Split into chunks]
    C -->|SHA-256 fingerprint| D{Chunk already in datastore?}
    D -->|Yes| E[Reference existing chunk]
    D -->|No| F[Zstd compress chunk]
    F -->|AES-256-GCM encrypt| G[Upload encrypted chunk]
    E --> H[Write snapshot manifest]
    G --> H
    H --> I[Snapshot committed]
```

For VMs and containers, every step in this pipeline runs **on the hypervisor host**.
For physical hosts, it runs **on the host itself** via the `ironcore-backup-client`
package. In both cases the backup server only ever sees encrypted chunks — it
cannot decrypt them without the key, which is held by the workload owner.

***

## Core Concepts

<CardGroup cols={2}>
  <Card title="Block-Level Change Tracking" icon="circle-dot" color="#bf9667">
    The hypervisor records which blocks have been modified since the previous
    backup. Only modified blocks are read, hashed, and uploaded. Unmodified
    blocks are skipped entirely.
  </Card>

  <Card title="Content-Defined Chunks" icon="layers" color="#bf9667">
    Source data is split into variable-sized chunks at boundaries determined by
    content fingerprints. Identical chunks always produce the same identifier,
    enabling cross-source deduplication.
  </Card>

  <Card title="Compression" icon="file-archive" color="#bf9667">
    Zstandard compression is applied per-chunk before encryption. Typical
    workloads compress at 2-4x with negligible CPU overhead — multiple gigabytes
    per second on modern hardware.
  </Card>

  <Card title="Client-Side Encryption" icon="lock" color="#bf9667">
    Each chunk is encrypted with AES-256 in Galois/Counter Mode (GCM) using a
    key held only by the workload owner. The backup server stores ciphertext
    with no ability to decrypt.
  </Card>
</CardGroup>

***

## What a Snapshot Contains

Every backup produces a **snapshot** — an immutable, named point-in-time view
of the workload.

| Component               | Description                                                 |
| ----------------------- | ----------------------------------------------------------- |
| **Manifest**            | Metadata, hash list, owner, timestamp, source ID, signature |
| **Chunk index**         | Ordered list of chunk identifiers (SHA-256 fingerprints)    |
| **Encrypted chunks**    | Per-chunk encrypted ciphertext, addressed by fingerprint    |
| **Verification record** | Per-chunk SHA-256 hash for integrity verification           |

Snapshots in the same backup group (for example, all snapshots of `vm/12345`) share
chunks through deduplication. Removing one snapshot does not affect the others —
chunks are garbage-collected only when no live snapshot references them.

***

## Restore Pipeline

```mermaid theme={null}
graph LR
    A[Select snapshot] --> B[Read manifest]
    B --> C[Stream encrypted chunks]
    C -->|AES-256-GCM decrypt| D[Decrypt on client]
    D -->|Zstd decompress| E[Reassemble blocks]
    E --> F[Mount or write to target]
    F --> G[Start VM / write files]
```

Restore reverses the backup pipeline. The client fetches encrypted chunks from the
datastore, decrypts them locally with the project's key, decompresses, and writes
the reassembled data to the target — a new VM, a host filesystem, or a file
download.

***

## Live-Restore

For VM workloads, IBS supports **live-restore**: the VM is registered and powered
on as soon as the manifest is read, then chunks are streamed on demand while the
guest OS is running.

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Dashboard
    participant Hypervisor as Compute Host
    participant IBS as IBS Datastore

    User->>Dashboard: Click Live-Restore
    Dashboard->>Hypervisor: Register VM definition
    Hypervisor->>IBS: Read manifest
    Hypervisor->>User: VM is running (background restore in progress)
    loop For each block accessed by VM
        Hypervisor->>IBS: Fetch encrypted chunk
        IBS-->>Hypervisor: Ciphertext
        Hypervisor->>Hypervisor: Decrypt and serve to guest
    end
    Hypervisor-->>Dashboard: Restore complete
```

The guest OS becomes accessible in seconds, even for terabyte-class VMs. The
remaining blocks are pulled in the background and seamlessly served to the guest
as the OS accesses them.

***

## Retention and Pruning

Snapshots are retained according to the policy attached to the backup job or
datastore. The most common retention windows are:

| Window           | Meaning                                                     |
| ---------------- | ----------------------------------------------------------- |
| `keep-last=N`    | Keep the most recent N snapshots regardless of age          |
| `keep-hourly=N`  | Keep the most recent snapshot for each of the last N hours  |
| `keep-daily=N`   | Keep the most recent snapshot for each of the last N days   |
| `keep-weekly=N`  | Keep the most recent snapshot for each of the last N weeks  |
| `keep-monthly=N` | Keep the most recent snapshot for each of the last N months |
| `keep-yearly=N`  | Keep the most recent snapshot for each of the last N years  |

The **Prune Simulator** in the Dashboard previews which snapshots a retention
policy would remove before any data is deleted.

***

## Where Backups Are Stored

<AccordionGroup>
  <Accordion title="Primary DC Datastore" icon="database" defaultOpen>
    Local datastore at the Primary DC for daily incremental and weekly full
    backups. Sized for short-term recovery scenarios — typical retention 1 week
    daily, 3 weeks weekly.
  </Accordion>

  <Accordion title="Backup Site Datastore" icon="server">
    Remote datastore at the Backup site. Receives a replicated copy of every
    weekly full backup for long-term archival. Typical retention 52 weeks.
  </Accordion>

  <Accordion title="Tape Library" icon="archive">
    Optional offline archive. Weekly full backups are written to LTO tape and
    catalogued for compliance scenarios that require offline media.
  </Accordion>

  <Accordion title="Object Storage" icon="cloud">
    Optional S3-compatible object storage backend for elastic capacity or
    geographic redundancy beyond the on-premises Backup site.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Create a Backup" icon="copy" href="/services/ironcore-backup/user-guide/create-backup" color="#bf9667">
    Create your first on-demand backup of a VM, container, or host
  </Card>

  <Card title="Backup Jobs" icon="calendar" href="/services/ironcore-backup/user-guide/backup-jobs" color="#bf9667">
    Schedule recurring backups with retention windows
  </Card>

  <Card title="Restore Options" icon="rotate-ccw" href="/services/ironcore-backup/user-guide/restore-options" color="#bf9667">
    Compare live-restore, full restore, and file-level restore
  </Card>

  <Card title="Architecture" icon="layers" href="/services/ironcore-backup/admin-guide/architecture" color="#bf9667">
    Deeper architectural detail for administrators
  </Card>
</CardGroup>