shc backup
What a .bak file is
Section titled “What a .bak file is”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:
| Verb | Command | What you get |
|---|---|---|
| export | shc 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. |
| restore | shc backup restore --file <archive> | A direct restore from the file, on this cluster or any other. No ledger row, no repository. |
| import | shc 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.
shc backup create
Section titled “shc backup create”Create a backup of a stack:
shc backup create --stack nextcloud # into the repositoryshc backup create --stack nextcloud --file /srv/handover # one-off .bak in a folder you nameshc backup create --stack nextcloud --file /srv/handover/nc.bak # or at an exact pathshc backup create --stack nextcloud --with-dependantsshc backup create --stack nextcloud --all-connectedWithout --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.
shc backup ls
Section titled “shc backup ls”List backups:
shc backup lsshc backup ls --stack nextcloudshc backup ls --output jsonFor 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.
shc backup restore
Section titled “shc backup restore”Restore data to an existing stack:
shc backup restore --file /tmp/myapp.bakshc backup restore --file /tmp/myapp.bak --stack myappshc backup restore --id abc123 --stack myapp
# Time-based restore (relative intervals only)shc backup restore --stack myapp --before "2h" # 2 hours agoshc backup restore --stack myapp --before "1d" # 1 day agoshc backup restore --stack myapp --before "30m" # 30 minutes ago
# Restore with connected stacksshc backup restore --id abc123 --with-connected # Same consistency_idshc backup restore --id abc123 --with-dependants # Stack and dependantsshc backup export
Section titled “shc backup export”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:
# Into a folder you name: the archive is <dir>/<backup-id>.bakshc backup export --id abc123 --file /srv/handover
# Or at an exact pathshc backup export --id abc123 --file /srv/handover/myapp.bak
# Multiple backups -> .bkg group fileshc 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 stackshc backup export -s myapp --latest --file /srv/handoverThere is no default output folder. An export with no --file is refused:
[X400417BKPOUT] backup export needs a destination, there is no default folderfor one-off archives. Name one with --file (a directory, or a full pathending 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.
shc backup import
Section titled “shc backup import”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:
shc backup import /srv/handover/myapp.bakshc -t other-org backup import /srv/handover/myapp.bak # Import into a different tenantshc backup import /srv/handover/backups.bkg # Uses manifests for placementThe container is checked first
Section titled “The container is checked first”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'scontainer is not sound, the container's member table accounts for only1945571322 of the 19455651066 bytes the repository holds: 17510079744 bytesare described by no member; manifest.json declares 6777 bytes, backup.tardeclares 1945564416 bytes. backup.tar's declared size is exactly the firstten digits of 19455644160, which is the ar(5) ten-character size field losinga 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
X400853BKMARZclamp, written by builds predating that refusal): refused by default, but the container’s geometry provably resolves the true member length, so--repair-containerimports it knowingly:Terminal window shc backup import --repair-container /var/lib/shc/dr/openobserve.bakRecapture the stack afterwards: an archive that reads only through the repair is not one to keep relying on.
Importing twice leaves one row
Section titled “Importing twice leaves one row”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.
shc backup verify
Section titled “shc backup verify”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:
shc backup verify abc123shc backup rm
Section titled “shc backup rm”Delete a backup by ID. The confirmation prompt is skipped with -y/--yes
(there is no --force):
shc backup rm abc123shc backup rm abc123 --yesshc backup export -e
Section titled “shc backup export -e”The latest backup of a stack in one environment:
shc backup export -s myapp -e prod --latest --file /tmp/prod.bakshc backup group
Section titled “shc backup group”Create a .bkg (backup group) file from multiple .bak files:
shc backup group -b app.bak -b db.bak --out combined.bkgshc backup group -b app.bak -b db.bak -b cache.bak --out /tmp/full-system.bkgshc backup ungroup
Section titled “shc backup ungroup”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:
shc backup ungroup /tmp/combined.bkgThe 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).
shc backup inspect
Section titled “shc backup inspect”Display manifest information from .bak or .bkg files:
# Inspect a single backupshc backup inspect myapp.bak
# Inspect a backup groupshc backup inspect combined.bkg
# Output formatsshc backup inspect myapp.bak --output jsonshc backup inspect myapp.bak --output yamlshc backup inspect myapp.bak --output tableshc recover
Section titled “shc recover”Create new deployments from backup files (top-level command):
# 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.bakshc recover -b myapp.bak=newapp -b mydb.bak=newdb
# From .bkg group file (using -b)shc recover -b combined.bkgshc recover -b combined.bkg --rename oldapp=newapp --rename olddb=newdb
# Target environmentshc recover -f myapp.bak -e prod
# Skip integrations during recoveryshc 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-runshc backup sync
Section titled “shc backup sync”Synchronize backup metadata with the Restic repository:
shc backup syncshc backup sync --stack myappRolling back to a safety snapshot
Section titled “Rolling back to a safety snapshot”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:
shc backup restore --stack myapp --before "2h" # ~2 hours agoshc backup restore --stack myapp --before "1d" # ~1 day agoshc 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.