Ironcore Backup CLI Reference - Polystack Documentation

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.

Prerequisites

An active Polystack account with project membership
The ironcore-backup CLI installed — see CLI Setup
An API token or interactive credentials with appropriate roles

Authentication

Interactive Login
API Token
Environment File

Interactive login

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.

Use an API token

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.

Source environment

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.

Backup Operations

`ironcore-backup backup create`

Create a one-shot backup of a workload.

ironcore-backup backup create \
  --type vm \
  --source-id 12345 \
  --repository ibs-primary \
  --namespace production

ironcore-backup backup create \
  --type container \
  --source-id 200 \
  --repository ibs-primary \
  --namespace production

ironcore-backup backup create \
  --type host \
  --source /srv/data \
  --backup-id app-data \
  --repository ibs-primary \
  --namespace hosts

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.

Live-restore a VM

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.

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 a tar archive

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`

List snapshots in a datastore

ironcore-backup snapshot list ibs-primary

Filter by namespace

ironcore-backup snapshot list ibs-primary --namespace production

Filter by source

ironcore-backup snapshot list ibs-primary --backup-id vm/12345

`ironcore-backup snapshot show`

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

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

`ironcore-backup snapshot remove`

ironcore-backup snapshot remove ibs-primary:vm/12345/2026-04-01T00:00:00Z

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

Backup Jobs

`ironcore-backup job create`

Schedule a recurring backup.

Daily incremental at 02:00 with 7-day retention

ironcore-backup job create \
  --name daily-prod \
  --schedule "02:00" \
  --type vm \
  --source-id 12345 \
  --repository ibs-primary \
  --namespace production \
  --retention keep-daily=7

Weekly full backup with 3-week retention

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`

ironcore-backup job list

`ironcore-backup job run`

Trigger a scheduled job immediately.

ironcore-backup job run --name daily-prod

Datastores and Namespaces

`ironcore-backup datastore create`

ironcore-backup datastore create \
  --name ibs-primary \
  --type local \
  --path /mnt/backup/ibs-primary

ironcore-backup datastore create \
  --name ibs-archival \
  --type s3 \
  --endpoint https://s3.<your-domain> \
  --bucket polystack-backup-archival \
  --region default

`ironcore-backup namespace create`

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.

Weekly archival sync to Backup site

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`

ironcore-backup sync run --name primary-to-backup-archival

Verification

`ironcore-backup verify start`

Verify all snapshots in a datastore

ironcore-backup verify start ibs-primary

Verify a single snapshot

ironcore-backup verify start ibs-primary:vm/12345/2026-05-21T00:00:00Z

`ironcore-backup verify status`

ironcore-backup verify status --job-id verify-2026-05-21

Encryption Keys

`ironcore-backup key create`

Generate a client-side encryption key

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.

ironcore-backup key paperkey /etc/ironcore/keys/ibs-prod-key.json > paperkey.pdf

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

Tape Operations

`ironcore-backup tape backup`

ironcore-backup tape backup \
  --pool yearly-archive \
  --include "keep-yearly=*" \
  --eject

`ironcore-backup tape inventory`

ironcore-backup tape inventory --library lto-library-01

`ironcore-backup tape restore`

ironcore-backup tape restore \
  --media TAPE0042 \
  --target ibs-primary

Diagnostics

`ironcore-backup status`

ironcore-backup status

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

`ironcore-backup task list`

ironcore-backup task list --since "1h ago"

`ironcore-backup task log`

ironcore-backup task log --upid <task-id>

Next Steps

Create a Backup

Step-by-step procedure to create your first backup.

Schedule a Job

Build recurring backup jobs that match your retention policy.

Restore Options

Compare live-restore, full restore, and file-level restore.

Admin Guide

Provision datastores, retention, replication, and security as an administrator.

​Overview

​Authentication

​Backup Operations

​ironcore-backup backup create

​Restore Operations

​ironcore-backup vm restore

​ironcore-backup file restore

​Snapshot Management

​ironcore-backup snapshot list

​ironcore-backup snapshot show

​ironcore-backup snapshot remove

​Backup Jobs

​ironcore-backup job create

​ironcore-backup job list

​ironcore-backup job run

​Datastores and Namespaces

​ironcore-backup datastore create

​ironcore-backup namespace create

​Replication and Sync

​ironcore-backup sync create

​ironcore-backup sync run

​Verification

​ironcore-backup verify start

​ironcore-backup verify status

​Encryption Keys

​ironcore-backup key create

​ironcore-backup key paperkey

​Tape Operations

​ironcore-backup tape backup

​ironcore-backup tape inventory

​ironcore-backup tape restore

​Diagnostics

​ironcore-backup status

​ironcore-backup task list

​ironcore-backup task log

​Next Steps

Create a Backup

Schedule a Job

Restore Options

Admin Guide

Overview

Authentication

Backup Operations

`ironcore-backup backup create`

Restore Operations

`ironcore-backup vm restore`

`ironcore-backup file restore`

Snapshot Management

`ironcore-backup snapshot list`

`ironcore-backup snapshot show`

`ironcore-backup snapshot remove`

Backup Jobs

`ironcore-backup job create`

`ironcore-backup job list`

`ironcore-backup job run`

Datastores and Namespaces

`ironcore-backup datastore create`

`ironcore-backup namespace create`

Replication and Sync

`ironcore-backup sync create`

`ironcore-backup sync run`

Verification

`ironcore-backup verify start`

`ironcore-backup verify status`

Encryption Keys

`ironcore-backup key create`

`ironcore-backup key paperkey`

Tape Operations

`ironcore-backup tape backup`

`ironcore-backup tape inventory`

`ironcore-backup tape restore`

Diagnostics

`ironcore-backup status`

`ironcore-backup task list`

`ironcore-backup task log`

Next Steps