Durability & recovery

Signed local snapshot backups

Takes a copy of the data directory from the admin API, with a signed manifest that shows what the copy contains and what it leaves out.

BetaEngine edition 5f8ea3af

What it does

POST /admin/db/backup copies the data directory into a timestamped folder under it, skipping prior backups and file object storage, and publishes a manifest signed with HMAC-SHA256 under an externally supplied key. Named backup profiles can be saved, but the local snapshot driver is the one that runs.

How it works

A backup request copies the data directory into backups/<name> through a staging directory and publishes it once a signed manifest is durable, and not before. Symlinks are not followed. The copy skips the backups directory and the file object directory, and the manifest declares file objects as excluded. A failure leaves no partial or staging residue, and a publication that has to roll back does so with synced renames.

The manifest is signed with a dedicated backup-signing key, taken from KYNETRA_BACKUP_SIGNING_KEYS as a list of key-id:base64 entries. The first key signs and later keys stay available to verify older backups, which supports rotation. Each key must decode to at least 32 bytes, and the signing key is never derived from the authentication secret and never part of a backup. GET /admin/db/restore-backups/{name}/manifest returns the manifest and whether its signature verifies.

GET and POST /admin/db/backup-profiles list and save profiles. A profile names a driver (local_snapshot, s3, r2, gcs or azure_blob), but local_snapshot is the executable driver: running a profile with any other driver answers that the driver is configured but not executable in this build. POST /admin/db/backup-profiles/{name}/run takes a backup under a profile. DELETE /admin/db/restore-backups/{name} removes one.

A backup is refused while the engine is recovery-uncertain, so an unresolved rewind is never copied as if it were authoritative.

Where you reach it

  • HTTPPOST /admin/db/backup; GET, POST /admin/db/backup-profiles; POST /admin/db/backup-profiles/{name}/run
  • HTTPGET /admin/db/restore-backups/{name}/manifest; DELETE /admin/db/restore-backups/{name}
  • ConfigKYNETRA_BACKUP_SIGNING_KEYS (key-id:base64, comma-separated)

Limits

  • The copy lives on the same disk as the data directory. It is not an off-host backup; use the portable bundle push, or copy the folder out, for that.
  • The copy is made file by file while the server runs and does not pause writers, so it is not a copy at one log position. For a consistent single-position copy, use portable bundles, which read from a pinned snapshot.
  • The copy contains everything in the data directory, including stored secrets such as the authentication signing secret. Protect it like the data directory itself.
  • The download route returns 501, and the s3, r2, gcs and azure_blob drivers cannot run.
  • File object bytes are not part of the copy.
  • Backups are not scheduled by this route; a profile runs when it is called.
  • The backup-signing key must be configured, or the route returns an error.

Evidence

  • On this siteReliability
  • TestsCovered in the engine repository by manifest sign, verify and tamper tests, key-rotation tests, tests that a backup is published together with a durable signed manifest, tests that failures leave no residue, and a test that symlinks are not followed

Test coverage is listed as present in the engine repository at this edition. This page does not report test results.

KynetraDB is in private preview

Request a preview to talk through the limits above against your own workload.