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

# Ironcore Backup CLI Reference

> Complete CLI reference for Ironcore Backup Solution — manage backups, restores, datastores, jobs, verification, and replication from the command line.

## Overview

The `ironcore-backup` CLI manages every aspect of Ironcore Backup Solution — backup
operations, restore operations, datastores, namespaces, jobs, retention policies,
replication, and encryption keys. The CLI is available on all Polystack control plane
nodes and on any host where the backup client package is installed.

<Note>
  **Prerequisites**

  * An active Polystack account with project membership
  * The `ironcore-backup` CLI installed — see [CLI Setup](/cli-setup)
  * An API token or interactive credentials with appropriate roles
</Note>

***

## Authentication

<Tabs>
  <Tab title="Interactive Login" icon="user">
    ```bash title="Interactive login" theme={null}
    ironcore-backup login \
      --repository ibs-primary@backup.<your-domain>:datastore \
      --realm polystack
    ```

    The CLI prompts for password and, if enabled, the second factor. Credentials are
    cached in `~/.config/ironcore-backup/credentials` for the session.
  </Tab>

  <Tab title="API Token" icon="key">
    ```bash title="Use an API token" theme={null}
    export IBS_TOKEN_ID="alice@polystack!backup-job"
    export IBS_TOKEN_SECRET="04c3...e72f"

    ironcore-backup snapshot list ibs-primary
    ```

    Use API tokens for scripts and automation. Tokens can be revoked without
    rotating the user password.
  </Tab>

  <Tab title="Environment File" icon="file-code">
    ```bash title="Source environment" theme={null}
    source /etc/ironcore/backup-rc.sh

    ironcore-backup snapshot list ibs-primary
    ```

    The environment file exports `IBS_REPOSITORY`, `IBS_TOKEN_ID`, and
    `IBS_TOKEN_SECRET` from a single sourced file. Used by deployment automation.
  </Tab>
</Tabs>

***

## Backup Operations

### `ironcore-backup backup create`

Create a one-shot backup of a workload.

<CodeGroup>
  ```bash title="Backup a VM" theme={null}
  ironcore-backup backup create \
    --type vm \
    --source-id 12345 \
    --repository ibs-primary \
    --namespace production
  ```

  ```bash title="Backup a container" theme={null}
  ironcore-backup backup create \
    --type container \
    --source-id 200 \
    --repository ibs-primary \
    --namespace production
  ```

  ```bash title="Backup a host directory" theme={null}
  ironcore-backup backup create \
    --type host \
    --source /srv/data \
    --backup-id app-data \
    --repository ibs-primary \
    --namespace hosts
  ```
</CodeGroup>

| Flag           | Type                          | Required           | Description                              |
| -------------- | ----------------------------- | ------------------ | ---------------------------------------- |
| `--type`       | `vm` \| `container` \| `host` | yes                | Workload type                            |
| `--source-id`  | string                        | yes (vm/container) | Source workload identifier               |
| `--source`     | path                          | yes (host)         | Source path on the host                  |
| `--backup-id`  | string                        | yes (host)         | Backup identifier for grouping snapshots |
| `--repository` | string                        | yes                | Target datastore                         |
| `--namespace`  | string                        | no                 | Namespace within the datastore           |
| `--keyfile`    | path                          | no                 | Client-side encryption key file          |
| `--include`    | glob                          | no                 | File patterns to include                 |
| `--exclude`    | glob                          | no                 | File patterns to exclude                 |

***

## Restore Operations

### `ironcore-backup vm restore`

Restore an entire VM. Use `--live` to start the VM immediately while restore continues
in the background.

```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 \
  --live
```

| Flag            | Description                                    |
| --------------- | ---------------------------------------------- |
| `--snapshot`    | Source snapshot reference                      |
| `--target-host` | Compute host to restore to                     |
| `--live`        | Start VM while restore continues in background |
| `--storage`     | Target storage backend                         |
| `--rename`      | Optional new name for the restored VM          |

### `ironcore-backup file restore`

Restore individual files or directories from a snapshot.

```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 a tar 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.tar.zst
```

***

## Snapshot Management

### `ironcore-backup snapshot list`

```bash title="List snapshots in a datastore" theme={null}
ironcore-backup snapshot list ibs-primary
```

```bash title="Filter by namespace" theme={null}
ironcore-backup snapshot list ibs-primary --namespace production
```

```bash title="Filter by source" theme={null}
ironcore-backup snapshot list ibs-primary --backup-id vm/12345
```

### `ironcore-backup snapshot show`

Show metadata, size, and the file listing inside a snapshot.

```bash theme={null}
ironcore-backup snapshot show ibs-primary:vm/12345/2026-05-21T00:00:00Z
```

### `ironcore-backup snapshot remove`

```bash theme={null}
ironcore-backup snapshot remove ibs-primary:vm/12345/2026-04-01T00:00:00Z
```

<Warning>
  Removing a snapshot is irreversible. Run `--dry-run` first to confirm the impact
  on deduplication and downstream incremental chains.
</Warning>

***

## Backup Jobs

### `ironcore-backup job create`

Schedule a recurring backup.

```bash title="Daily incremental at 02:00 with 7-day retention" theme={null}
ironcore-backup job create \
  --name daily-prod \
  --schedule "02:00" \
  --type vm \
  --source-id 12345 \
  --repository ibs-primary \
  --namespace production \
  --retention keep-daily=7
```

```bash title="Weekly full backup with 3-week retention" theme={null}
ironcore-backup job create \
  --name weekly-full \
  --schedule "Sun 03:00" \
  --type vm \
  --source-id 12345 \
  --repository ibs-primary \
  --namespace production \
  --mode full \
  --retention keep-weekly=3
```

### `ironcore-backup job list`

```bash theme={null}
ironcore-backup job list
```

### `ironcore-backup job run`

Trigger a scheduled job immediately.

```bash theme={null}
ironcore-backup job run --name daily-prod
```

***

## Datastores and Namespaces

### `ironcore-backup datastore create`

<CodeGroup>
  ```bash title="Local datastore" theme={null}
  ironcore-backup datastore create \
    --name ibs-primary \
    --type local \
    --path /mnt/backup/ibs-primary
  ```

  ```bash title="S3-compatible object storage" theme={null}
  ironcore-backup datastore create \
    --name ibs-archival \
    --type s3 \
    --endpoint https://s3.<your-domain> \
    --bucket polystack-backup-archival \
    --region default
  ```
</CodeGroup>

### `ironcore-backup namespace create`

```bash theme={null}
ironcore-backup namespace create ibs-primary production
ironcore-backup namespace create ibs-primary staging
```

***

## Replication and Sync

### `ironcore-backup sync create`

Replicate snapshots from a local datastore to a remote site.

```bash title="Weekly archival sync to Backup site" theme={null}
ironcore-backup sync create \
  --name primary-to-backup-archival \
  --source ibs-primary \
  --remote backup-site \
  --remote-repository ibs-archival \
  --schedule "Sun 04:30" \
  --direction push \
  --include "keep-weekly=*" \
  --encrypt
```

| Flag                  | Description                                                 |
| --------------------- | ----------------------------------------------------------- |
| `--source`            | Local datastore name                                        |
| `--remote`            | Configured remote site name                                 |
| `--remote-repository` | Datastore name on the remote site                           |
| `--direction`         | `push` (local → remote) or `pull` (remote → local)          |
| `--schedule`          | systemd-style schedule (for example `Sun 04:30` or `daily`) |
| `--encrypt`           | Encrypt snapshots in transit                                |
| `--bwlimit`           | Maximum bandwidth in MiB/s                                  |

### `ironcore-backup sync run`

```bash theme={null}
ironcore-backup sync run --name primary-to-backup-archival
```

***

## Verification

### `ironcore-backup verify start`

```bash title="Verify all snapshots in a datastore" theme={null}
ironcore-backup verify start ibs-primary
```

```bash title="Verify a single snapshot" theme={null}
ironcore-backup verify start ibs-primary:vm/12345/2026-05-21T00:00:00Z
```

### `ironcore-backup verify status`

```bash theme={null}
ironcore-backup verify status --job-id verify-2026-05-21
```

***

## Encryption Keys

### `ironcore-backup key create`

```bash title="Generate a client-side encryption key" theme={null}
ironcore-backup key create \
  --name ibs-prod-key \
  --type aes256-gcm \
  --output /etc/ironcore/keys/ibs-prod-key.json
```

### `ironcore-backup key paperkey`

Print the encryption key as a paper-friendly QR + hex block for offline secure storage.

```bash theme={null}
ironcore-backup key paperkey /etc/ironcore/keys/ibs-prod-key.json > paperkey.pdf
```

<Danger>
  If the encryption key is lost, the encrypted backups are unrecoverable. Always
  store the paperkey in a physical safe at the Backup site.
</Danger>

***

## Tape Operations

### `ironcore-backup tape backup`

```bash theme={null}
ironcore-backup tape backup \
  --pool yearly-archive \
  --include "keep-yearly=*" \
  --eject
```

### `ironcore-backup tape inventory`

```bash theme={null}
ironcore-backup tape inventory --library lto-library-01
```

### `ironcore-backup tape restore`

```bash theme={null}
ironcore-backup tape restore \
  --media TAPE0042 \
  --target ibs-primary
```

***

## Diagnostics

### `ironcore-backup status`

```bash theme={null}
ironcore-backup status
```

Returns service health, datastore usage, scheduled jobs, and active tasks.

### `ironcore-backup task list`

```bash theme={null}
ironcore-backup task list --since "1h ago"
```

### `ironcore-backup task log`

```bash theme={null}
ironcore-backup task log --upid <task-id>
```

***

## Next Steps

<CardGroup cols={4}>
  <Card title="Create a Backup" icon="copy" href="/services/ironcore-backup/user-guide/create-backup" color="#bf9667">
    Step-by-step procedure to create your first backup.
  </Card>

  <Card title="Schedule a Job" icon="calendar" href="/services/ironcore-backup/user-guide/backup-jobs" color="#bf9667">
    Build recurring backup jobs that match your retention policy.
  </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="Admin Guide" icon="shield-check" href="/services/ironcore-backup/admin-guide" color="#bf9667">
    Provision datastores, retention, replication, and security as an administrator.
  </Card>
</CardGroup>