backup.yaml lists what a backup copies: 2026-10-18
Owner ruling, 2026-10-18 (SHC-3508). A package’s backup.yaml lists the
mounts a backup copies under include, and nothing it leaves out is
captured. The durability: block, exclude.mounts and the include.mounts
mapping are gone. The reference is
App definition: backup.yaml.
The ruling, verbatim
Section titled “The ruling, verbatim”“a package’s backup.yaml LISTS the volumes and mounts that hold data worth backing up. Anything not listed is stateless (generated, cache, ephemeral) and is never captured. An empty backup.yaml means the app has nothing to back up, so a backup of it does nothing and succeeds”
Settled while building it
Section titled “Settled while building it”These are the main session’s calls on the lane, not Clay’s words.
keep lists persistent data another path protects, such as a tree a dump
hook packs into an included mount, or one the image owns. A relocation
carries it and shc uninstall --data names it (X200975DURDEL), but a
backup never reads it and it never counts toward the per-node refusal
(X409899BKPRPL). keep is for data protected by another path (a dump hook, an image-owned tree), not a way to skip backups.
So every keep entry carries a comment saying what protects it, and
tests/unit/catalog fails a package whose entry has none.
Every mount in neither list is scratch: never captured, recreated empty
wherever its replica lands, and never reported by doctor’s
storage.durable-on-node-disk. A mount in either list is durable, so its
reach is a hard placement rule and block storage holds it. An empty file
(comments only, or include: []) backs up the deployment config and the
vault bundle and succeeds. A host-path data volume neither list names stays
kept, as SHC-2583 has it: carried on a move, named on a delete, and copied
only when include names it.
A converter’s mount must be under include, and install refuses one that
isn’t (X400603BKPCNV). The converter stands in for its mount only on the
orchestrated pass. Paused-tar, a failed converter and the daemonless tar copy
the mount itself, and they copy only what’s listed. A hook that dumps into a
volume lists the dump target under include and the live source under
keep: gitlab’s pre_backup packs its repositories into gitlab-backups,
which it includes, and it keeps gitlab-data.
A package that declares the include list (below) and named volumes and
ships no backup.yaml is refused at install (X400601BKPUND), and the
catalogue lint refuses it too. A package with no volumes needs no file.
In such a package exclude.mounts, the include.mounts mapping and
durability: are refused by name (X400345DURSHP), and a mount under both
lists refuses X400339DURCON. Every reader goes through one reader (ce
modules/app/backup_list.go): the orchestrated pass, paused-tar, the
converter fallback, the daemonless CLI tar, the restic path, group restore,
placement, the move plan and the delete warning.
Deployments and packages from v0.1.21
Section titled “Deployments and packages from v0.1.21”v0.1.21 is the upgrade baseline (the 10-18 gap brief, rule 11), and 3508 ships in v0.1.22. After the upgrade a v0.1.21 deployment never captures less than v0.1.21 did, with no step by hand.
Which grammar a backup.yaml is in is the package’s declared property: a
package whose app.yaml sets requires.shc to 0.1.22 or later is read as
include and keep lists. Every other package keeps v0.1.21’s meaning until
the deployment is updated onto one that declares it
(ce modules/app/backup_list_v0121.go). No file, or one that names no
mounts, captures every mount; include.mounts captures those;
exclude.mounts captures every other mount; a converter’s mount is captured
through it. A mount v0.1.21 did not capture and its placement held durable
is kept. A file without the declaration that already holds include or
keep as lists is read as lists, since v0.1.21 could not read it.
A fresh install of such a package is not refused: it reads the same way. A
recover, clone or move of a v0.1.21 deployment replays its package and is
never refused for the grammar it was written in, and an archive v0.1.21 made
restores. Doctor’s app.backup-v0121-meaning names each deployment on a node
read this way and what it captures, at INFO, since nothing needs doing.
ce’s shcFeatures table holds a row for backup.yaml at 0.1.22, so
shc app validate and the catalogue sweep make every package that ships one
declare requires.shc: "0.1.22". The index carries that per version, and a
v0.1.21 node, whose parser fails on an include: list, is never offered a
converted package: a sync keeps it on the last version it reads.
What it supersedes
Section titled “What it supersedes”Models ruling M6 (2026-08-14) put
durability in a durability: block beside the exclude list, with critical
and ephemeral. Its point stands: one declaration, read by both move and
delete. That declaration is now the two lists.
SHC-1231’s redirect rule is gone. It held every left-out volume of a package
with converters, jobs or a backup hook as durable, because a job might dump
it into a captured one. The hook’s source now says so under keep. The
doctor check app.backup-undeclared, which warned about a package with
volumes and no file, is gone too, since install refuses that package.
SHC-3497 declared the system traefik’s static mount under exclude.mounts
and durability.ephemeral. Traefik now lists nothing. SHC-3504, which asked
for durability.ephemeral alone to stop a capture, is moot: there’s no
ephemeral left.
The catalogue conversion
Section titled “The catalogue conversion”Every package moved to the new shape in the same change, and capture is unchanged for all of them except four mounts that were declared ephemeral and still captured. Those stop riding backups:
- activepieces
activepieces-cache - ethereum
jwt-data - onlyoffice
onlyoffice-dataandonlyoffice-logs
Eleven mounts in four packages were captured by nothing but held durable.
They sit under keep now, each with its reason:
- gitlab
gitlab-dataandgitlab-config - seven wazuh trees:
filebeat-var,wazuh-active-response,wazuh-dashboard-config,wazuh-dashboard-custom,wazuh-integrations,wazuh-security-configandwazuh-wodles - jellyfin
jellyfin-preupgrade - matrix
synapse-modules
The system traefik lists nothing, so a backup of it carries its deployment config and vault bundle and succeeds.