Skip to content
SHC Docs

shc backup

Scheduled backups go into the cluster’s restic repository and nowhere else: encrypted, indexed in the ledger, verifiable, mountable, and swept by retention. There is no local backups folder.

A .bak file is the one-off format, and it supports exactly three things:

VerbCommandWhat you get
exportshc backup create -s <stack> --file <dir|path>
shc backup export -i <id> --file <dir|path>
A portable archive at a location you name. There is no default folder, and omitting the destination is refused with X400417BKPOUT.
restoreshc backup restore --file <archive>A direct restore from the file, on this cluster or any other. No ledger row, no repository.
importshc backup import <archive>The archive ingested into the indexed store: a restic snapshot plus a ledger row, addressable by ID from then on.

A one-off .bak is not indexed, not encrypted, and never reclaimed by retention. Where it lives is your decision, and deleting it when you are done is your responsibility.

Create a backup of a stack:

Terminal window
shc backup create --stack nextcloud # into the repository
shc backup create --stack nextcloud --file /srv/handover # one-off .bak in a folder you name
shc backup create --stack nextcloud --file /srv/handover/nc.bak # or at an exact path
shc backup create --stack nextcloud --with-dependants
shc backup create --stack nextcloud --all-connected

Without --file the archive goes into the cluster’s restic repository and is indexed. With --file you get a one-off .bak at the location you name and nothing is added to the index; see What a .bak file is above.

List backups:

Terminal window
shc backup ls
shc backup ls --stack nextcloud
shc backup ls --output json

For browsing backups stored in the Restic repository, use shc backup ls (above) and filter with --stack / --status / --all-tenants (--limit and --offset page the result). There is no --id filter: a single backup is addressed by positional ID on shc backup verify / rm / restore. To inspect a local .bak / .bkg file’s manifest, see shc backup inspect below.

Restore data to an existing stack:

Terminal window
shc backup restore --file /tmp/myapp.bak
shc backup restore --file /tmp/myapp.bak --stack myapp
shc backup restore --id abc123 --stack myapp
# Time-based restore (relative intervals only)
shc backup restore --stack myapp --before "2h" # 2 hours ago
shc backup restore --stack myapp --before "1d" # 1 day ago
shc backup restore --stack myapp --before "30m" # 30 minutes ago
# Restore with connected stacks
shc backup restore --id abc123 --with-connected # Same consistency_id
shc backup restore --id abc123 --with-dependants # Stack and dependants

Export backups from the Restic repository to portable .bak or .bkg files. --file is required: it names either a directory to put the archive in (the file is named for the backup) or the full path you want:

Terminal window
# Into a folder you name: the archive is <dir>/<backup-id>.bak
shc backup export --id abc123 --file /srv/handover
# Or at an exact path
shc backup export --id abc123 --file /srv/handover/myapp.bak
# Multiple backups -> .bkg group file
shc backup export --id abc123 --id def456 --file /srv/handover/backups.bkg
# Export with related backups (--with-connected needs an --id to group around)
shc backup export --id abc123 --with-connected --file /srv/handover/group.bkg
# Export the latest backup of a stack
shc backup export -s myapp --latest --file /srv/handover

There is no default output folder. An export with no --file is refused:

[X400417BKPOUT] backup export needs a destination, there is no default folder
for one-off archives. Name one with --file (a directory, or a full path
ending in the archive name)

This replaced a fallback that wrote under $SHC_STATE_HOME/exports (or the OS temp dir): a folder nobody chose, holding archives that no ledger row addresses and no retention pass can reclaim.

Exactly one of --id or -s/--stack is required, and naming neither, or both, fails with X400002VALINP (“either --id or -s/--stack is required”, “cannot use both --id and -s/--stack”). A stack named only in $SHC_STACK or shc ctx -s does not choose the latest backup: -s has to be typed.

Ingest a one-off .bak (or a .bkg) into the cluster’s Restic repository: the bytes become a snapshot and the archive becomes an ordinary row in shc backup ls, addressable by ID for restore, verify, mount and retention. This is the on-ramp for an archive somebody handed you, or for one this cluster exported earlier. The archive path is a positional argument; there is no --file flag and no preview mode:

Terminal window
shc backup import /srv/handover/myapp.bak
shc -t other-org backup import /srv/handover/myapp.bak # Import into a different tenant
shc backup import /srv/handover/backups.bkg # Uses manifests for placement

Before anything is written, the archive’s ar(5) member table has to add up against the file’s own length. An archive that does not add up is refused rather than sealed:

[X400416IMPCNT] import of /srv/handover/openobserve.bak refused, the archive's
container is not sound, the container's member table accounts for only
1945571322 of the 19455651066 bytes the repository holds: 17510079744 bytes
are described by no member; manifest.json declares 6777 bytes, backup.tar
declares 1945564416 bytes. backup.tar's declared size is exactly the first
ten digits of 19455644160, which is the ar(5) ten-character size field losing
a leading digit, the fault X400853BKMARZ names …

The check is O(1) in the archive (one stat and one 64 KiB read), so it runs on a 60 GB archive for the same cost as a 6 KB one. It exists because import is the only verb that turns foreign bytes into a completed ledger row: once the snapshot lands, the row is indistinguishable from a real capture, so the door is the last cheap place to tell them apart.

Two shapes, two outcomes:

  • Truncated (a member’s payload ends past the end of the file): refused with or without any flag. No arithmetic recovers bytes that are not there.

  • ar(5) size-field overflow (the X400853BKMARZ clamp, written by builds predating that refusal): refused by default, but the container’s geometry provably resolves the true member length, so --repair-container imports it knowingly:

    Terminal window
    shc backup import --repair-container /var/lib/shc/dr/openobserve.bak

    Recapture the stack afterwards: an archive that reads only through the repair is not one to keep relying on.

Import is idempotent on the archive’s own content identity. A second run of the same command recognises the archive, returns the existing row, and stages nothing: no new backup ID, no gigabytes spooled, no second snapshot in the repository. Retry a failed import freely; a runbook does not need to know whether the previous step finished.

A different archive still imports normally: the identity discriminates, it does not swallow.

Confirm a backup’s snapshot still exists in its repository (a membership check; it does not scan the snapshot’s contents for corruption). It takes a backup ID, positionally; it cannot verify a loose .bak file, because the check is a snapshot-membership lookup against the repository. Use shc backup inspect to read a local file:

Terminal window
shc backup verify abc123

Delete a backup by ID. The confirmation prompt is skipped with -y/--yes (there is no --force):

Terminal window
shc backup rm abc123
shc backup rm abc123 --yes

The latest backup of a stack in one environment:

Terminal window
shc backup export -s myapp -e prod --latest --file /tmp/prod.bak

Create a .bkg (backup group) file from multiple .bak files:

Terminal window
shc backup group -b app.bak -b db.bak --out combined.bkg
shc backup group -b app.bak -b db.bak -b cache.bak --out /tmp/full-system.bkg

Extract the member .bak files from a .bkg group file. The .bkg path is a positional argument and the command takes no flags; in particular the destination is not selectable:

Terminal window
shc backup ungroup /tmp/combined.bkg

The extracted .bak files land in $SHC_STATE_HOME/exports when SHC_STATE_HOME is set, and in the system temp directory otherwise. The command prints nothing but a confirmation, so set SHC_STATE_HOME if you need them somewhere predictable. Each extracted member is also re-registered in the backup index on a best-effort basis, so shc backup ls finds it, but the archive data itself is not restaged into Restic (use shc backup import for that).

Display manifest information from .bak or .bkg files:

Terminal window
# Inspect a single backup
shc backup inspect myapp.bak
# Inspect a backup group
shc backup inspect combined.bkg
# Output formats
shc backup inspect myapp.bak --output json
shc backup inspect myapp.bak --output yaml
shc backup inspect myapp.bak --output table

Create new deployments from backup files (top-level command):

Terminal window
# Single .bak file (using -f / --file)
shc recover -f myapp.bak
# Single .bkg group file (using -f / --file, auto-expands to individual .bak files)
shc recover -f combined.bkg
# Multiple .bak files (using -b / --from-backup)
shc recover -b myapp.bak -b mydb.bak
shc recover -b myapp.bak=newapp -b mydb.bak=newdb
# From .bkg group file (using -b)
shc recover -b combined.bkg
shc recover -b combined.bkg --rename oldapp=newapp --rename olddb=newdb
# Target environment
shc recover -f myapp.bak -e prod
# Skip integrations during recovery
shc recover -b combined.bkg --skip-integration traefik
# Rewrite ingress hostnames during recovery (--override does hostnames only:
# [<stack>:]host:<old>=<new> or [<stack>:]hosts=<new>; anything else is
# refused with X400048RCVINP. Rename stacks with --rename)
shc recover -b combined.bkg --override myapp:host:old.example.com=new.example.com
# Dry run (preview without executing)
shc recover -b combined.bkg --dry-run

Synchronize backup metadata with the Restic repository:

Terminal window
shc backup sync
shc backup sync --stack myapp

Install, update, and restore each take an automatic pre_* safety snapshot before changing a deployment (skip with --no-rollback). Restore one (or any point in time) with shc backup restore --before:

Terminal window
shc backup restore --stack myapp --before "2h" # ~2 hours ago
shc backup restore --stack myapp --before "1d" # ~1 day ago
shc backup restore --stack myapp --before "2w" # ~2 weeks ago

--before takes a relative interval only: an integer plus one of m (minutes), h (hours), d (days) or w (weeks). Calendar dates and Go durations with seconds are rejected with X400973RLBKTM. To restore a specific snapshot, find its ID with shc backup ls and pass --id.