Skip to main content
ALTCHA®

Snapshots & backups

A snapshot is a copy of Sentinel's database in one ZIP file, optionally encrypted with age. Use snapshots to back up a deployment, to roll back after a mistake, and to move data to a new deployment. Snapshots are on by default and need no license feature.

Only root users can create and restore snapshots, in the admin UI under Snapshots or through the /v2/snapshots API with a session token. API keys are never accepted; other users get 403 ROOT_PRIVILEGES_REQUIRED.

Modes

Two settings decide what Create snapshot produces: whether [snapshots] identity holds an age key, and whether a [storage] provider is configured.

[storage] provider[snapshots] identityCreate returnsStored list, restore by name, schedule
s3 or azureset201: an encrypted .zip.age, stored under storage_prefixYes
noneset200: an encrypted .zip.age downloadNo
anyunset200: a plain .zip downloadNo

A stored snapshot is always encrypted. When [storage] is configured without an identity, for example for email attachments only, snapshots stay downloads and startup warns:

WARN [storage] is configured but [snapshots] identity is not: snapshots are downloads, not stored

Uploaded files can be restored in every mode. Startup logs the active mode:

INFO snapshots storage=false encrypted=true schedule="none"

Configure snapshots

A minimal setup that stores an encrypted snapshot in S3 every night and keeps the last 14:

[storage]
provider = "s3"
# bucket, region and credentials: see Object storage

[snapshots]
identity   = "${file:/run/secrets/snapshots.key}"   # age-keygen output
recipients = ["age1…"]        # offline recovery key; optional
schedule   = "0 3 * * *"      # cron, evaluated in UTC
keep       = 14               # scheduled snapshots kept; manual ones are never deleted
KeyPurpose
enabledfalse removes the /v2/snapshots routes (404) and stops scheduled snapshots.
identityage X25519 secret key that encrypts new snapshots and decrypts them on restore.
recipientsExtra age public keys (age1…) that can also decrypt new snapshots. Needs identity.
scheduleCron expression in UTC, or @daily and the like. Needs identity and a [storage] provider.
keepNumber of scheduled snapshots kept; 0 keeps all.
storage_prefixKey prefix of snapshots in [storage].
exclude_tablesTables to leave out, such as request_logs. Only tables without relations qualify.
max_upload_sizeLargest file accepted by an upload restore.

Defaults, ranges, and the tables exclude_tables accepts are in the Configuration reference. A key that breaks a dependency stops startup, for example snapshots.schedule requires snapshots.identity and a [storage] provider.

Storage transfers of a snapshot may take up to 1 hour, whatever [storage] timeout says. Each snapshot is uploaded in a single request, so it can be at most 5 GiB on S3 and about 5000 MiB on Azure. See Timeouts and size limits.

Encrypt snapshots with age

  1. Generate the server's key pair with age-keygen:

    age-keygen -o snapshots.key
    Public key: age1nje0ztaq5m9axuu7fzfnstrqfdeujpsqs4xzadrshvuy3pxgvekq5zq94g

    The file holds the secret key (AGE-SECRET-KEY-1…) with comment lines. Sentinel reads it as it is, so mount it as a secret and point identity at it with ${file:…}.

  2. Generate a recovery key pair on an offline machine:

    age-keygen -o recovery.key

    Put only its public key in recipients. Keep recovery.key offline, for example in a password manager or a safe. It decrypts every snapshot made after you added it, even if the server's identity is lost.

  3. Restart Sentinel. New snapshots are encrypted to both keys. Snapshots made earlier keep the recipients they were made with.

To inspect a snapshot outside Sentinel, decrypt it with either key:

age -d -i recovery.key sentinel-20261119T092549.831Z-manual.zip.age > snapshot.zip
unzip -l snapshot.zip

What a snapshot contains

The archive holds one CSV file per table plus manifest.json:

accounts.csv  alerts.csv  api_keys.csv  audit_logs.csv  login_countries.csv
passkeys.csv  push_subscriptions.csv  request_logs.csv  request_stats.csv
roles.csv  security_groups.csv  similarity_embeddings.csv  threat_entries.csv
threat_sources.csv  training_data.csv  training_suggestions.csv  users.csv
user_accounts.csv  manifest.json

That covers accounts, users with their passwords, roles, passkeys and TOTP secrets, security groups, API keys, threat sources and entries, training data, alerts, audit logs, and the request logs and stats kept in the main database.

A snapshot never contains:

  • The license tables (license_state, license_slots). The license belongs to the deployment and stays in place on restore.
  • Tables in exclude_tables.
  • Data outside the database: the configuration file, [secrets] and <data_dir>/secrets.json, the KV store (rate limits, penalties, replay and cache entries), downloaded remote files, request logs in ClickHouse, and email attachments in [storage].

Create a snapshot

In the admin UI, open Snapshots and select Create snapshot. In download mode the browser saves the file; keep it somewhere safe. With storage, the snapshot appears in the list.

Through the API, see Create a snapshot in the API reference. In download mode, save the body:

curl -X POST https://sentinel.example.com/v2/snapshots \
  -H 'Authorization: Bearer <jwt>' \
  -OJ
HTTP/1.1 200 OK
content-type: application/zip
content-disposition: attachment; filename="sentinel-20261119T092535.363Z-manual.zip"

The content-type is application/octet-stream for an encrypted .zip.age. With storage, the response is 201 with the snapshot's details:

{
  "data": {
    "name": "sentinel-20261104T071509.362Z-manual.zip.age",
    "createdAt": "2026-11-04T07:15:09.362Z",
    "trigger": "manual",
    "size": 6881,
    "encrypted": true,
    "tables": [{ "name": "accounts", "rows": 1 }, { "name": "roles", "rows": 3 }, …],
    "rows": 16
  }
}

Names follow sentinel-<UTC time>-<manual|scheduled>.zip[.age]. Every create is recorded in the audit log as snapshot.create.

List stored snapshots

The Snapshots page lists stored snapshots, newest first. Through the API, see List snapshots:

curl -H 'Authorization: Bearer <jwt>' https://sentinel.example.com/v2/snapshots
{
  "data": [
    {
      "name": "sentinel-20261104T071509.362Z-manual.zip.age",
      "createdAt": "2026-11-04T07:15:09.362Z",
      "trigger": "manual",
      "size": 6881,
      "encrypted": true
    }
  ]
}

The list holds every object directly under storage_prefix whose name follows the naming scheme. Without storage, the endpoint answers 400 SNAPSHOT_STORAGE_DISABLED:

{"code":"SNAPSHOT_STORAGE_DISABLED","error":"Snapshot storage needs a [storage] provider and [snapshots] identity.","statusCode":400}

Sentinel has no endpoint to download or delete a stored snapshot. Fetch or remove the object in your bucket or container with the provider's tools; files you download that way can be restored as uploads. Deleting manual snapshots is up to you, because retention only prunes scheduled ones.

Scheduled snapshots and retention

On each schedule occurrence, one replica makes a snapshot named after the occurrence time, such as sentinel-20261104T030000.000Z-scheduled.zip.age. It then deletes the oldest scheduled snapshots, keeping the newest keep. If another replica already made the occurrence, or a snapshot or restore is running, the occurrence is skipped with a log line. A failed occurrence is logged as an error and isn't retried; the next one runs as usual.

Restore a snapshot

In the admin UI, open Snapshots and select Restore next to a stored snapshot, or Restore from file to upload a .zip or .zip.age. Through the API, restore a stored snapshot by name with POST /v2/snapshots/<name>/_restore, or upload a file to POST /v2/snapshots/_restore:

# A stored snapshot, by name
curl -X POST -H 'Authorization: Bearer <jwt>' \
  https://sentinel.example.com/v2/snapshots/sentinel-20261104T071509.362Z-manual.zip.age/_restore

# A file: send the raw bytes, not multipart
curl -X POST -H 'Authorization: Bearer <jwt>' \
  --data-binary @sentinel-20261119T092549.831Z-manual.zip.age \
  https://sentinel.example.com/v2/snapshots/_restore
{
  "data": {
    "tables": [{ "name": "accounts", "rows": 1 }, { "name": "alerts", "rows": 0 }, …],
    "rows": 25,
    "durationMs": 9,
    "warnings": []
  }
}

What happens on restore:

  • Format. Sentinel detects it from the content: an age file is decrypted with identity, a ZIP is used as it is. An encrypted file without an identity fails with SNAPSHOT_KEY_REQUIRED, and one encrypted to other keys with SNAPSHOT_DECRYPT_FAILED.
  • Scope. Tables in the archive are replaced. Tables not in it, the license tables and excluded tables, keep their rows. An archive that contains a license table is refused.
  • Schema. A snapshot from an older schema gets default values for columns added since. One with columns the current schema lacks is refused with SNAPSHOT_MISMATCH.
  • Sessions. Users keep their ids and session versions, so sessions stay valid when the restored users match the current ones. Otherwise, users sign in again with the passwords from the snapshot.
  • Indexes. The threat and similarity indexes reload on this replica and, with an external [redis], on the others.
  • Audit. The restore is recorded as snapshot.restore, written after the import so it survives the replaced audit_logs.

One snapshot create or restore runs at a time across all replicas; a second one gets 409 SNAPSHOT_IN_PROGRESS. Uploads larger than max_upload_size get 413 PAYLOAD_TOO_LARGE. All snapshot errors are listed in Error codes.

Restore into a fresh deployment

To move data to a new deployment, or to recover after losing one:

  1. Start the new deployment with the old [secrets]. Use the same encryption_key and, ideally, jwt_secret. With embedded SQLite and no [secrets] set, copy the old <data_dir>/secrets.json into the new data directory before the first start. Use the same [database] table_prefix, and the same [snapshots] identity for encrypted snapshots.

  2. Sign in as root with the new deployment's bootstrap password.

  3. Restore the snapshot as an upload.

  4. Sign in again with a root password from the snapshot. The users were replaced, so the session from step 2 ends.

API key secrets and TOTP secrets are stored encrypted with encryption_key. If the new deployment uses a different key, the restore succeeds, but the restored API keys can't sign challenges or authenticate, and TOTP sign-in fails. Recreate those keys and second factors, or restart with the old key. See Server secrets.

The license isn't part of the snapshot. Configure it on the new deployment as usual; see Configure the license.

To bring in data from Sentinel v1, convert its snapshot first; see Migrating data from v1.

Table prefix

With [database] table_prefix, the archive holds the prefixed table names, while exclude_tables and the API responses use the names without the prefix. A snapshot restores only under the prefix it was made with: a restore refuses tables that aren't Sentinel's under the current prefix with INVALID_SNAPSHOT, so it never empties another application's tables in a shared database.

Remote ExotDB

With [database] url pointing at an ExotDB server (http:// or https://), the export and import run on that server. It needs [export_import] enabled = true in its own configuration, and Sentinel's [database] token must be an admin token. Otherwise every create and restore fails with 502 DATABASE_TRANSFER_REFUSED.

Volume and database backups

Snapshots copy Sentinel's tables only. You can also, or instead, back up at a lower level:

DatabaseBackupNotes
Embedded SQLiteThe data volume (<data_dir>, /home/nonroot/data in the container by default)Copy it while Sentinel is stopped, or take a consistent copy of the running database with sqlite3 sentinel.db ".backup '/backup/sentinel.db'". A plain file copy of a running database can be inconsistent. Back up secrets.json with it.
PostgreSQL, MySQL, MariaDB, SQL Server, OracleThe database's native tools (pg_dump, mysqldump, point-in-time recovery, managed-service backups)Covers the license tables and the built-in KV store's tables too. Back up [secrets] separately.
ExotDB serverThe backend database it servesAs above.

Native backups restore the whole database as it was, license included, and suit disaster recovery of the same deployment. Snapshots suit moving data between deployments, restoring through the admin UI, and keeping encrypted off-site copies without database access.

Start typing to search...

↑ ↓ Navigate ↵ Select