feat(backup): check a backup against what is in place, changing nothing (#5823)
CI / lint (push) Successful in 3s
CI / integration (push) Successful in 1m23s
CI / unit (push) Successful in 1m37s
CI / publish (push) Successful in 1m8s

#5823 "Check a backup: compare what it would restore with what is in
place, without restoring".

- steward/backup/check.py: pg_restore writes the backup's rows as COPY
  text with no database involved. The rows in place go out through COPY in
  the same form. Tables are compared on their primary keys, over the columns
  both sides have, and grouped by area.
- Sealed values are opened with each side's own key and compared as
  plaintext digests, so a secret sealed twice still matches. They are never
  shown. A backup whose key can't open its own secrets fails the check.
- What Steward records as it runs (last-seen times, a schedule's last run,
  backup history, scraped UniFi fields) is left out of the comparison:
  contents.ACTIVITY, STATE_SETTINGS and HAND_SET_ONLY.
- Settings → Backups:
  - a Check button on each sent backup, which fetches it from the bucket
    (new s3.get_file);
  - "Check a file" to upload one, with the size limit raised before the
    CSRF check reads the form;
  - a results page.
- Each backup Steward sends checks itself once written, and its history
  row says how that went.
- New CLI command `steward check-backup FILE`. CI's image smoke step checks a
  real backup against its source and expects a match.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-15 10:48:48 -04:00
co-authored by Claude Opus 5.5
parent e6da0ff299
commit e8b75143f1
16 changed files with 1141 additions and 10 deletions
+36
View File
@@ -79,6 +79,42 @@ While backups are on, Steward records two metrics under the source
A rule such as `backup_age_secs > 93600` (26 hours) fires when a daily backup
has been missed.
## Checking a backup
**Settings → Backups → Check** compares a backup with what is in place, without
changing anything. It shows what a restore would bring back, change or remove.
Each row under Recent backups has its own Check button, and **Check a file**
takes a file downloaded from the bucket. From a shell:
```sh
docker exec -u app <steward container> steward check-backup /tmp/steward-20261015T030000Z.tar
```
The check reports:
- for each area (Settings, Users and API tokens, Hosts and agents, Monitors,
Alert rules, Ansible, Dashboards, Plugins), how many entries are the same,
differ, are only in the backup or are only here;
- each setting that differs, with both values. A password or key shows only
"differs": sealed values are opened with their own key and compared, never
shown;
- whether the backup's secret key is the one in use, and whether it opens the
backup's own sealed values. A backup whose key can't open them fails the
check, because its secrets would not come back;
- whether the backup was made by this Steward's schema, an older one or a
newer one.
What Steward records as it runs is left out of the comparison: when an agent
or monitor was last seen, a schedule's last run, the backup history. These
change by the minute. The list is `ACTIVITY` and `STATE_SETTINGS` in
`steward/backup/contents.py`.
Each backup Steward sends is checked once it is written, and its row under
Recent backups says so. A backup is sent even when its check can't run.
Checking a backup on the bucket reads it back from there. An append-only key
may not be allowed to; the page then says AccessDenied, and the file can be
downloaded and checked with **Check a file** instead.
## Making a backup by hand
```sh