Skip to content
SHC Docs

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.

“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”

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.

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.

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.

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-data and onlyoffice-logs

Eleven mounts in four packages were captured by nothing but held durable. They sit under keep now, each with its reason:

  • gitlab gitlab-data and gitlab-config
  • seven wazuh trees: filebeat-var, wazuh-active-response, wazuh-dashboard-config, wazuh-dashboard-custom, wazuh-integrations, wazuh-security-config and wazuh-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.