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

# Create a Backup

> Create on-demand backups of virtual machines, system containers, and physical hosts using the Polystack Dashboard or the ironcore-backup CLI.

## Overview

Create an immediate, one-shot backup of a workload using either the Polystack
Dashboard or the `ironcore-backup` CLI. On-demand backups are useful before risky
changes, for evidence capture, or for any workload not yet covered by a scheduled
job. The same procedure works for virtual machines, system containers, and physical
hosts.

<Note>
  **Prerequisites**

  * An active Polystack account with project membership
  * At least one datastore visible to your project
  * The workload to back up is running or accessible
  * For host backups, the `ironcore-backup` client must be installed on the host
</Note>

***

## Workload Types

<CardGroup cols={3}>
  <Card title="Virtual Machine" icon="server" color="#bf9667">
    Block-level change tracking captures only modified blocks. The VM remains
    running for the full duration of the backup.
  </Card>

  <Card title="System Container" icon="box" color="#bf9667">
    Filesystem-level backup of an Ironcore system container. Files are captured
    consistently via a snapshot read.
  </Card>

  <Card title="Physical Host" icon="hard-drive" color="#bf9667">
    File-archive backup of any host where the backup client runs. Useful for
    config, application data, and bare-metal protection.
  </Card>
</CardGroup>

***

## Create a VM Backup

<Tabs>
  <Tab title="Dashboard" icon="gauge">
    <Steps titleSize="h3">
      <Step title="Open the Backup Solution" icon="external-link">
        From the main navigation, choose **Backup Solution** > **Snapshots**.
      </Step>

      <Step title="Click Create" icon="plus">
        In the top-right corner of the snapshots list, click **Create**. The
        Create Backup dialog opens.
      </Step>

      <Step title="Select the source" icon="search">
        For **Workload type**, choose **Virtual Machine**. Pick the VM from the
        searchable list. Only VMs your project owns are shown.
      </Step>

      <Step title="Choose the datastore and namespace" icon="database">
        Select the target **Datastore** and (optionally) a **Namespace**.
        Datastores not visible to your project are hidden from the dropdown.
      </Step>

      <Step title="Set encryption" icon="lock">
        Select **Use project encryption key** to encrypt the backup with the
        project's master key. Backups created without a key cannot be encrypted
        retroactively.
      </Step>

      <Step title="Optional notes" icon="message">
        Add a **Comment** to identify the snapshot — for example, "pre-upgrade
        snapshot 2026-05-21". Comments are visible in the snapshot list.
      </Step>

      <Step title="Start the backup" icon="play">
        Click **Create**. A live task panel opens showing block scan progress
        and bytes transferred.

        <Check>The snapshot appears in the list with status **Available** once complete.</Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="Create a VM backup" theme={null}
    ironcore-backup backup create \
      --type vm \
      --source-id 12345 \
      --repository ibs-primary \
      --namespace production \
      --comment "pre-upgrade snapshot 2026-05-21"
    ```

    Track progress in real time:

    ```bash title="Stream task logs" theme={null}
    ironcore-backup task list --since "5m ago"
    ironcore-backup task log --upid <task-id> --follow
    ```

    <Check>Backup complete when the CLI prints `TASK OK`.</Check>
  </Tab>
</Tabs>

***

## Create a Container Backup

<Tabs>
  <Tab title="Dashboard" icon="gauge">
    <Steps titleSize="h3">
      <Step title="Open Snapshots" icon="external-link">
        Navigate to **Backup Solution** > **Snapshots** and click **Create**.
      </Step>

      <Step title="Select the source" icon="search">
        For **Workload type**, choose **Container**. Pick the container from
        the list.
      </Step>

      <Step title="Pick exclusions" icon="filter">
        Optionally add paths to **Exclude** — for example `/var/cache` or
        application-managed staging directories.
      </Step>

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

        <Check>The container snapshot appears in the list when complete.</Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="Create a container backup" theme={null}
    ironcore-backup backup create \
      --type container \
      --source-id 200 \
      --repository ibs-primary \
      --namespace production \
      --exclude "/var/cache/**" \
      --exclude "/tmp/**"
    ```

    <Check>Backup complete when the CLI prints `TASK OK`.</Check>
  </Tab>
</Tabs>

***

## Create a Host Backup

<Tabs>
  <Tab title="CLI" icon="terminal">
    Host backups run on the host itself.

    ```bash title="Install the backup client on the host" theme={null}
    sudo apt-get install ironcore-backup-client
    ```

    ```bash title="Back up /srv to the project datastore" theme={null}
    ironcore-backup backup create \
      --type host \
      --backup-id $(hostname)-srv \
      --source /srv \
      --repository ibs-primary \
      --namespace hosts \
      --include "/srv/data" \
      --include "/srv/app/config"
    ```

    | Flag          | Description                                                                     |
    | ------------- | ------------------------------------------------------------------------------- |
    | `--backup-id` | Backup group name. Repeated backups with the same ID build an incremental chain |
    | `--include`   | Paths to include. Repeat for multiple paths                                     |
    | `--exclude`   | Paths to exclude. Repeat for multiple paths                                     |
    | `--keyfile`   | Optional client-side encryption key file                                        |

    <Check>Host backup complete when the CLI prints `TASK OK`.</Check>
  </Tab>
</Tabs>

***

## Validation

After the backup completes, verify it is browsable:

<Tabs>
  <Tab title="Dashboard" icon="gauge">
    Open the snapshot in **Snapshots** and click **File Browser**. The full file
    tree should load within a few seconds.
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="List files inside the snapshot" theme={null}
    ironcore-backup snapshot show ibs-primary:vm/12345/2026-05-21T00:00:00Z
    ```
  </Tab>
</Tabs>

<Tip>
  For high-confidence verification, also trigger a one-shot SHA-256 verify pass
  on the new snapshot. See [Verification and Validation](/services/ironcore-backup/admin-guide/verification-validation).
</Tip>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="No datastore visible in the dropdown" icon="alert-triangle">
    Your project may not have access to any datastore. Contact your administrator
    and request the **Datastore Backup** role on the appropriate datastore.
  </Accordion>

  <Accordion title="Backup fails with `permission denied`" icon="lock">
    The API token or user lacks `Datastore.Backup` permission on the target
    datastore or namespace. Verify the role assignment in **Access Control**.
  </Accordion>

  <Accordion title="`source not reachable` for a VM" icon="server">
    The VM may be paused, migrating, or the hypervisor agent is unresponsive.
    Resume the VM, wait for migration to complete, or check the compute host
    health.
  </Accordion>

  <Accordion title="Host backup hangs at 0%" icon="hard-drive">
    The host cannot reach the backup datastore on TCP/8007. Check network
    connectivity and firewall rules between the host and the backup server.
  </Accordion>
</AccordionGroup>

***

## Next Steps

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

  <Card title="Restore Options" icon="rotate-ccw" href="/services/ironcore-backup/user-guide/restore-options" color="#bf9667">
    Restore a full VM or individual files from this backup
  </Card>

  <Card title="Monitoring Jobs" icon="activity" href="/services/ironcore-backup/user-guide/monitoring-jobs" color="#bf9667">
    Track active and historical backup tasks
  </Card>

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