# Snapshots & backups

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

A snapshot is a copy of Sentinel's database in one ZIP file, optionally encrypted with [age](https://age-encryption.org). 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]`](/docs/sentinel/v2/configure/storage/) provider is configured.

| `[storage] provider` | `[snapshots] identity` | Create returns | Stored list, restore by name, schedule |
| --- | --- | --- | --- |
| `s3` or `azure` | set | `201`: an encrypted `.zip.age`, stored under `storage_prefix` | Yes |
| `none` | set | `200`: an encrypted `.zip.age` download | No |
| any | unset | `200`: a plain `.zip` download | No |

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:

```text
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:

```text
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:

```toml
[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
```

| Key | Purpose |
| --- | --- |
| `enabled` | `false` removes the `/v2/snapshots` routes (`404`) and stops scheduled snapshots. |
| `identity` | age X25519 secret key that encrypts new snapshots and decrypts them on restore. |
| `recipients` | Extra age public keys (`age1…`) that can also decrypt new snapshots. Needs `identity`. |
| `schedule` | Cron expression in UTC, or `@daily` and the like. Needs `identity` and a `[storage]` provider. |
| `keep` | Number of scheduled snapshots kept; `0` keeps all. |
| `storage_prefix` | Key prefix of snapshots in `[storage]`. |
| `exclude_tables` | Tables to leave out, such as `request_logs`. Only tables without relations qualify. |
| `max_upload_size` | Largest file accepted by an upload restore. |

Defaults, ranges, and the tables `exclude_tables` accepts are in the [Configuration reference](/docs/sentinel/v2/reference/configuration/#snapshots). 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](/docs/sentinel/v2/configure/storage/#timeouts-and-size-limits).

## Encrypt snapshots with age

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

```bash
age-keygen -o snapshots.key
```

```text
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:**

```bash
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:

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

<Callout type="warning" title="Keep the identity away from the snapshots">

Store the identity outside the database and away from the storage bucket. Anyone with the identity and a snapshot can read every account, user, and API key. Without the identity or a recovery key, an encrypted snapshot can't be restored.

## What a snapshot contains

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

```text
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](/docs/sentinel/v2/operations/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](/sentinel-api-docs-v2.html#tag/snapshots/POST/v2/snapshots) in the API reference. In download mode, save the body:

```bash
curl -X POST https://sentinel.example.com/v2/snapshots \
-H 'Authorization: Bearer <jwt>' \
-OJ
```

```http
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:

```json
{
"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](/docs/sentinel/v2/operations/audit-logs/) as `snapshot.create`.

## List stored snapshots

The **Snapshots** page lists stored snapshots, newest first. Through the API, see [List snapshots](/sentinel-api-docs-v2.html#tag/snapshots/GET/v2/snapshots):

```bash
curl -H 'Authorization: Bearer <jwt>' https://sentinel.example.com/v2/snapshots
```

```json
{
"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`:

```json
{"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

<Callout type="danger" title="A restore overwrites the database">

Every table in the snapshot is emptied and refilled in one transaction. Accounts, users, API keys, and everything else made since the snapshot are lost. Create a snapshot first if you may want to go back.

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`](/sentinel-api-docs-v2.html#tag/snapshots/POST/v2/snapshots/_restore):

```bash
# 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
```

```json
{
"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](/docs/sentinel/v2/reference/errors/#snapshots).

### 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](/docs/sentinel/v2/configure/secrets/).

The license isn't part of the snapshot. Configure it on the new deployment as usual; see [Configure the license](/docs/sentinel/v2/configure/licensing/).

To bring in data from Sentinel v1, convert its snapshot first; see [Migrating data from v1](/docs/sentinel/v2/upgrade/migrate-data/).

## Table prefix

With [`[database] table_prefix`](/docs/sentinel/v2/configure/databases/#share-a-database-with-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:

| Database | Backup | Notes |
| --- | --- | --- |
| Embedded SQLite | The 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, Oracle | The 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 server | The backend database it serves | As 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.

## Related

- [Configuration reference: `[snapshots]`](/docs/sentinel/v2/reference/configuration/#snapshots)
- [Object storage](/docs/sentinel/v2/configure/storage/)
- [Server secrets](/docs/sentinel/v2/configure/secrets/)
- [Databases & KV store](/docs/sentinel/v2/configure/databases/)
- [Error codes: Snapshots](/docs/sentinel/v2/reference/errors/#snapshots)
- [Audit logs](/docs/sentinel/v2/operations/audit-logs/)
- [Migrating data from v1](/docs/sentinel/v2/upgrade/migrate-data/)
- [Snapshots in the API reference](/sentinel-api-docs-v2.html#tag/snapshots/GET/v2/snapshots)
