From 76057eb346190475fa21edbddcec61e1b60d4588 Mon Sep 17 00:00:00 2001 From: mrhid6 Date: Mon, 7 Sep 2026 14:45:37 +0000 Subject: [PATCH] fix: document inspect and --confirm-db's actual behaviour --- docs/operations/backup-and-restore.md | 46 ++++++++++++++++++++++----- 1 file changed, 38 insertions(+), 8 deletions(-) diff --git a/docs/operations/backup-and-restore.md b/docs/operations/backup-and-restore.md index 6db3026..57f60e8 100644 --- a/docs/operations/backup-and-restore.md +++ b/docs/operations/backup-and-restore.md @@ -130,6 +130,25 @@ Each line of output answers a different question: it worth putting on a schedule — a backup job that "succeeded" last night is not the same claim as a backup that will actually restore. +## Looking inside an archive + +`inspect` prints an archive's manifest and touches no database at all — no +`--mongo-uri`, no key. It is what to run against an archive of unknown origin, +before deciding whether it is the one you want: + +```bash +vantagectl inspect /backups/vantage-backup-vantage-20260907T020000Z.tar.gz +``` + +It reports when the archive was taken and on which host, the Vantage and +MongoDB versions behind it, the database it came from, the key fingerprint (or +that it carries none), every collection with its document count and size, and +anything `--exclude` left out. Opening the archive verifies every member's +checksum on the way, so a corrupt archive fails here too. + +Reach for `verify` instead when the question is whether the key you hold opens +it; reach for `inspect` when the question is what it is. + ## Restoring `restore` expects the target database to be empty. Pointed at one that already @@ -143,13 +162,25 @@ vantagectl restore /backups/vantage-backup-vantage-20260907T020000Z.tar.gz \ ``` To overwrite a database that is not empty, add `--force`, which drops each -collection named in the archive before loading it. On a terminal, `--force` -alone prompts you to type the target database's name back — a deliberate pause -before something destructive. With no terminal — a Kubernetes Job, a CI step, a -cron entry — that prompt cannot happen, so `--force` instead requires -`--confirm-db NAME` naming the target exactly; a mismatch is refused. Naming -the database in the command itself means a copy-pasted invocation carries its -intended target with it and cannot destroy a different one by accident. +collection named in the archive before loading it. `--force` always needs a +second assurance, in one of two forms: + +- `--confirm-db NAME`, naming the target exactly. A mismatch is refused. This + works everywhere — on a terminal and in a Kubernetes Job, a CI step or a cron + entry alike — and is the form to script. +- Nothing, on a terminal: `--force` alone prompts you to type the target + database's name back, a deliberate pause before something destructive. + +Without a terminal and without `--confirm-db`, `--force` is refused: there is +nobody there to prompt. Naming the database in the command itself means a +copy-pasted invocation carries its intended target with it and cannot destroy a +different one by accident. + +`--force` drops only the collections the archive carries. Anything else already +in the target is left alone and named in a warning, so an archive taken with +`--exclude workflow_log_lines` restored over a live database tells you the old +log lines are still there, joined to freshly restored runs. Dropping them +instead would delete data you never asked to delete. `restore` also refuses when the archive's key fingerprint does not match the `KEY_ENCRYPTION_KEY` in your environment — see "When the key is wrong" below. @@ -187,7 +218,6 @@ will come back with ciphertext nobody can read: - `secrets` — the vault - `auth_providers` — OIDC/SSO client secrets - `console_sessions` — RDP/VNC credentials -- `settings` — anything encrypted at the instance level There is no way to recover that ciphertext afterwards. If you have reached this point, the right key was lost along with the chance to read those rows —