# Migrating data from v1

> **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).

The `altcha-sentinel migrate` command converts a v1 snapshot into a v2 snapshot that you restore into your new instance. Accounts, users, API keys, security groups, threat lists, training data, and request logs come over with their ids, so existing widget keys and secrets keep working. This page covers the conversion, what is translated and what isn't, and how to copy request logs kept in ClickHouse.

Prerequisite: a running v2 instance with its final configuration, including the license and secrets. See the [upgrade checklist](/docs/sentinel/v2/upgrade/) for where this fits.

## What is migrated

| v1 data | In v2 |
|---|---|
| Accounts | Kept with their ids, names, and active and deleted state. |
| Users | Kept with ids, password hashes, OTP secrets, and root flags. `ldap:` usernames are lowercased; a later duplicate is skipped with a warning. |
| Memberships | Kept with their role (`admin`, `member`, or `readonly`). |
| Security groups | Kept with their access level. Rules are [translated](#how-security-group-rules-are-translated). No group gets a `role`. |
| API keys | Kept with ids, secrets, security group, and request logging (`none`, `verification`, or `all`). |
| Threat sources | Your own sources are kept. v1's default sources are replaced by the v2 defaults when `[threats] seed_defaults` is `true` (the default). |
| Threat entries | Manual entries that haven't expired. A `penalize` action becomes no action, with the score kept. |
| Training data | Imported watch-only: weight `0`, no threshold. Group names are lowercased, or sanitized when that isn't enough. |
| Request statistics | The hourly stats. |
| Request logs | The raw logs in the snapshot, unless you pass `--skip-logs`. Logs that v1 wrote to ClickHouse aren't in the snapshot; [copy them separately](#copy-clickhouse-request-logs). |

Secrets in the database, the API key secrets and OTP secrets, are re-encrypted with the v2 server's `[secrets] encryption_key`. Roles are seeded as on a fresh install.

## What isn't migrated

| v1 data | Why, or what replaces it |
|---|---|
| Forms and form submissions | Forms are removed. See [Contact & lead forms](/docs/sentinel/v2/use-cases/forms/). |
| Redirects and links | Removed, with no replacement. |
| Alerts | v2 raises its own alerts with new rules. |
| Access logs and error logs | v2 records logins and management changes in [audit logs](/docs/sentinel/v2/operations/audit-logs/). |
| Automatic threat entries | v2 creates its own from [threat signals](/docs/sentinel/v2/features/threat-intelligence/). |
| Disabled account features | Access is controlled by [roles](/docs/sentinel/v2/concepts/accounts-users/). |
| OAuth tokens | Users sign in again. |
| Redis data | Rate-limit counters, penalties, and replay claims start empty. v1 Redis snapshots can't be converted. |
| ClickHouse request logs | Not in the v1 snapshot. [Copy them in ClickHouse](#copy-clickhouse-request-logs). |
| Configuration | Environment variables don't migrate. See [Config mapping](/docs/sentinel/v2/upgrade/config-mapping/). |
| License | v2 needs a Sentinel V2 license in `[license]`. |

## Prerequisites

- v2 is installed and configured: license, `[database]`, `[secrets]`, and, if you use it, `[database] table_prefix`. The conversion depends on this configuration, so finish it first.
- The v2 database holds nothing you want to keep. Restoring replaces every table in the snapshot.
- You can sign in to the v1 admin app as root, and to the v2 admin UI.
- Disk space for the v1 snapshot and the converted file, which can be large with request logs.

## Step 1 — Take a v1 snapshot

In the v1 admin app, open **Admin → Snapshots → Create Snapshot**, or call `POST /v1/admin/snapshots/create`. Use a main-database snapshot; Redis snapshots can't be converted.

Get the `.tgz` file (or `.tgz.age` if v1 encrypted snapshots):

- With v1's `local` snapshot storage, the file is in the `backups` directory of the v1 data directory (`/data/backups` in the v1 Docker image).
- With S3 or Azure, download it from the bucket or container, under v1's `SNAPSHOTS_KEY_PREFIX`.

If the snapshot is encrypted, save v1's `SNAPSHOTS_AGE_SECRET_KEY` to a file, for example `old-identity.txt`. You'll pass it to `migrate`.

Changes made in v1 after this point aren't in the snapshot. For the final migration, stop changing v1's accounts, keys, and rules until traffic has moved to v2.

## Step 2 — Convert the snapshot

Run `migrate` in the v2 image with the **v2 server's configuration**: the same config file, environment variables, secret mounts, and data volume as the server. The output folder must be writable by the image's user:

```bash
mkdir -p migration && cp altcha-sentinel-2026-11-14T08_35_53.tgz migration/
sudo chown -R 65532 migration   # the image runs as uid 65532

docker run --rm \
--env-file sentinel.env \
-v "$PWD/sentinel.toml:/home/nonroot/sentinel.toml:ro" \
-v "$PWD/secrets:/run/secrets:ro" \
-v sentinel-data:/home/nonroot/data \
-v "$PWD/migration:/migration" \
ghcr.io/altcha-org/sentinel:2.0.0-beta.1 \
migrate /migration/altcha-sentinel-2026-11-14T08_35_53.tgz --output-dir /migration
```

For an encrypted v1 snapshot, copy the identity file into `migration/` too and add `--identity /migration/old-identity.txt`.

| Flag | Default | Description |
|---|---|---|
| `--output-dir <DIR>` | `.` | Where the converted snapshot is written; created if missing. |
| `--identity <FILE>` | — | The age identity that decrypts an encrypted v1 snapshot. If decryption fails, decrypt the file with `age -d` and pass the `.tgz`. |
| `--skip-logs` | off | Leave out the raw request logs, which can be large. The number left out is printed; hourly stats are still migrated. |

<Callout type="warning" title="Use the server's secrets">

`migrate` encrypts API key secrets and OTP secrets with the v2 `[secrets] encryption_key`. If the server that restores the file has another key, those secrets can't be decrypted: widget and backend keys fail. With embedded SQLite and no `[secrets]` set, the key is in `secrets.json` in `data_dir`, so mount the **server's** data volume, as above. Without it, `migrate` generates a new `secrets.json` that the server never sees.

The output is `sentinel-<time>-manual.zip`, or `.zip.age` when `[snapshots] identity` is set (it's encrypted to that identity and to `recipients`). `migrate` prints warnings to stderr, then the file and the rows per table:

```text
warning: security group Website (restricted): its API keys no longer work for the widget (/v2/challenge, /v2/verify accept only public keys)
warning: training data imported with weight 0 (watch-only) and the server default threshold; review each group with POST /v2/training-data/_evaluate and raise weights to re-enable
wrote /migration/sentinel-20261117T091503.512Z-manual.zip (1843201 bytes)
accounts: 2
users: 4
user_accounts: 5
security_groups: 3
api_keys: 4
…
restore it as root with POST /v2/snapshots/_restore (it replaces the whole database)
```

Keep the warnings; [Step 4](#step-4--review-the-result) explains them. If the file is larger than `[snapshots] max_upload_size` (default `1073741824` bytes), `migrate` says so: raise the limit and restart before restoring, or convert again with `--skip-logs`. See [CLI reference](/docs/sentinel/v2/reference/cli/#migrate).

## Step 3 — Restore it in v2

<Callout type="danger" title="Restore replaces the database">

Every table in the snapshot is emptied and refilled, including users and audit logs. Anything you created in v2 before the restore is gone, and so is the root user created on first start. The license is kept.

Sign in to the v2 admin UI as root, open **Snapshots → Restore from file**, choose the converted file, and confirm. The app reloads when the restore finishes.

Or upload it with a root session token. The body is the raw file:

```bash
curl -X POST https://sentinel.example.com/v2/snapshots/_restore \
-H 'Authorization: Bearer <root session jwt>' \
--data-binary @migration/sentinel-20261117T091503.512Z-manual.zip
```

```json
{ "data": { "tables": [{ "name": "accounts", "rows": 2 }, …], "rows": 18342, "durationMs": 912, "warnings": [] } }
```

The restore runs in one transaction. If a reverse proxy sits in front of Sentinel, raise its request body limit for this upload. Errors you may hit:

| HTTP | Code | Meaning |
|---|---|---|
| 400 | `INVALID_SNAPSHOT` | The file is a v1 snapshot that wasn't converted, or it was converted with another `[database] table_prefix`. |
| 400 | `SNAPSHOT_KEY_REQUIRED` | The file is encrypted, and the server has no `[snapshots] identity`. |
| 413 | `PAYLOAD_TOO_LARGE` | The file is larger than `[snapshots] max_upload_size`. |

See [Error codes](/docs/sentinel/v2/reference/errors/#snapshots) and [Snapshots & backups](/docs/sentinel/v2/operations/snapshots/).

## Step 4 — Review the result

Sign in again with your **v1** username and password; the users now come from v1, with their OTP settings. Then work through the warnings:

| Warning | What to do |
|---|---|
| `security group … (restricted)` or `(full)`: `its API keys no longer work for the widget` | If the widget uses these keys, change the group's **Access** to `public`, or move the keys to a `public` group. See [Widget keys must be public](/docs/sentinel/v2/upgrade/breaking-changes/#widget-keys-must-be-public). |
| `security group … (full): its API keys have no management access until root assigns the group a role` | If automation uses these keys on management endpoints, set the group's role as root. See [Managing API keys](/docs/sentinel/v2/policies/api-keys/). |
| `rule '…' dropped` or `setting … dropped (no equivalent)` | Rebuild the rule with v2 conditions and settings. See [How security-group rules are translated](#how-security-group-rules-are-translated). |
| `training data imported with weight 0` | Review each group with **Training Data → Evaluate thresholds** (`POST /v2/training-data/_evaluate`), then raise the weights. Until then, training data has no effect. |
| `training group '…' renamed to '…'` | Update `classifier.similarityGroups` rules and API callers that use the old name. |
| `duplicate username 'ldap:…' skipped` | Two v1 LDAP users differ only by case. Both now sign in as the first one; move any memberships the skipped user had. |
| `threat source name '…' is not allowed` | Recreate the source under another name. |
| `N request logs not migrated (--skip-logs)` | Expected with `--skip-logs`. |

Also check:

- **Security groups.** Open each group and read its rules. Test changes in monitor mode before relying on them. See [Writing security rules](/docs/sentinel/v2/policies/security-rules/).
- **Threat sources.** Your custom sources are listed next to the new defaults.
- **Similarity.** Semantic matching needs `[similarity] provider`. See [Similarity & training data](/docs/sentinel/v2/features/similarity/).

## How security-group rules are translated

`migrate` converts each group's v1 rules into v2 rules, then validates them. The setting names are in [Breaking changes](/docs/sentinel/v2/upgrade/breaking-changes/#setting-names).

**Default rules.** A group whose rules were only v1's defaults (Autopilot, optionally with the default proof-of-work version rule) becomes:

- a `public` group: the **Recommended** preset (rules named `preset:recommended:*`);
- a `restricted` or `full` group: no rules (`[]`).

**Custom rules** are translated one by one:

| v1 | v2 |
|---|---|
| `allow`, `deny`, `set` | Same action. Other actions are dropped with a warning. |
| `autopilot = true` in a `public` group | The **Recommended** preset is inserted before that rule, once per group. |
| `codeChallenge = adaptive` | An extra rule `<name>:codeChallenge` with the same conditions plus `penalty >= 3`, setting `codeChallenge.enabled`. |
| `threats = true` | An extra `deny` rule `<name>:threats` with the same conditions plus `threatVerdict = block` and `path != /v2/verify`. Skipped when the Recommended preset was inserted. |
| `key = edk` or `ip` | Appended to each rate limit: `50/10m(key=edk)`. |
| `codeChallengeMinLength`, `codeChallengeMaxLength` | One `codeChallenge.length` range, `MIN-MAX`. |
| `algorithm` or `supportedAlgorithms` | `pow.algorithm` (the first supported algorithm). The v1 default, `PBKDF2/SHA-256`, is dropped because it is the v2 default. |
| `expires` in milliseconds | `pow.expires` with `ms`. |
| Conditions `hosting`, `proxy`, `tor`, `mobile` | `network`. |
| Conditions `malicious`, `bot` | `signal` = `MALICIOUS`, `BOT`. |
| Condition `country` with `list:` | The list name without `list:`. |

These are dropped, each with a warning:

- a rule with a condition that has no equivalent: a `penalty` range such as `4-10`, an `ip` value with `*`, or an unknown field;
- a setting without an equivalent (for example `ai`), while the rest of the rule is kept;
- a `set` rule left with no settings;
- an `adaptive` code challenge or `threats = true` in a rule whose conditions are joined with `or`;
- a rule that fails v2 validation, and any rules beyond the limit of 100.

Rule names lose a leading `#` and commas; unnamed rules become `legacy-1`, `legacy-2`, and so on. Rules use v2 semantics after the migration; see [Security groups & rules](/docs/sentinel/v2/concepts/security-groups/).

## Copy ClickHouse request logs

With `CLICKHOUSE_URL` set, v1 wrote request logs only to its ClickHouse `logs` table, so they aren't in the snapshot. v2 writes to a new `request_logs` table and doesn't read `logs`. Copy the old rows inside ClickHouse.

<Callout type="note" title="License required">

Requires the <code>clickhouse</code> license feature. Without it, v2 keeps request logs in the main database and doesn't use ClickHouse. See [Plans & Licensing](/docs/sentinel/v2/plans/).

This applies when v2 stores request logs in ClickHouse too. With ClickHouse, request-log search reads only `request_logs`, and stats read only its hourly rollup, so the hourly stats restored from the snapshot aren't used. Copying ClickHouse logs into the main database isn't covered. Map the connection settings with [Config mapping](/docs/sentinel/v2/upgrade/config-mapping/#clickhouse).

The steps assume `[clickhouse] database = "altcha_sentinel"`, so the old `logs` and the new `request_logs` are in one database. Otherwise, change the table names in the SQL.

### Step 1 — Restore the snapshot and start v2 with ClickHouse

Stop v1, so no more logs arrive, then convert and restore its snapshot as above. Accounts and API keys keep their ids, so the copied logs belong to them; logs of an account or key that wasn't migrated aren't visible.

Start v2 with `[clickhouse]`. It creates `request_logs` at startup; with `[clickhouse] auto_migrate = false`, apply the script of `altcha-sentinel schema sql --clickhouse` before you start it (see [Manual ClickHouse migrations](/docs/sentinel/v2/operations/schema-migrations/#manual-clickhouse-migrations)). Run `altcha-sentinel doctor`: `license.features` warns when the license lacks `clickhouse`.

### Step 2 — Create a helper function and a staging table

The function builds `log_…` ids. The staging table has the structure of `request_logs` without its TTL, so old months aren't dropped before you copy them:

```sql
CREATE FUNCTION IF NOT EXISTS sentinel_b32 AS (n, width) -> arrayStringConcat(
arrayMap(i -> substring('0123456789abcdefghijklmnopqrstuv', bitAnd(bitShiftRight(toUInt64(n), 5 * i), 31) + 1, 1),
       arrayReverse(range(width))));

CREATE TABLE altcha_sentinel.request_logs_import AS altcha_sentinel.request_logs;
ALTER TABLE altcha_sentinel.request_logs_import REMOVE TTL;
```

`CREATE FUNCTION` needs that privilege, and the function is global to the ClickHouse server.

### Step 3 — Write the import query

Save this as `import.sql`. It copies one month, one partition of `logs`, into the staging table:

```sql
INSERT INTO altcha_sentinel.request_logs_import (
id, ts, account_id, api_key_id, endpoint, method, path, status_code, latency_ms,
ip, user_ip, country_code, browser, device, network, referrer, verified,
verification_id, error, pow_algorithm, protection_level, his_automation, his_assistive,
triggered_rules, context
)
SELECT
concat('log_', sentinel_b32(toUInt64(time) * 1000, 9), sentinel_b32(1 + rand(1) % 9998, 3),
     sentinel_b32(1 + rand(2) % 4294967295, 7)),
toDateTime64(time, 3, 'UTC'),
accountId,
apiKeyId,
multiIf(endpoint = 1, 'challenge', endpoint = 2, 'verify', 'other'),
['GET', 'POST', 'PATCH', 'PUT', 'DELETE', 'OPTIONS', 'QUERY', 'HEAD'][method],
multiIf(endpoint = 1, '/v1/challenge', endpoint = 2, '/v1/verify', path),
statusCode,
serverLatency / 1000,
nullIf(replaceRegexpOne(toString(ip), '^::ffff:', ''), '::'),
NULL, -- user_ip
nullIf(lower(replaceAll(toString(countryCode), '\0', '')), ''),
nullIf(['chrome', 'firefox', 'edge', 'safari', 'brave', 'vivaldi', 'opera', 'app'][browser], ''),
nullIf(['desktop', 'console', 'mobile', 'tablet', 'smarttv', 'wearable', 'embedded', 'bot'][device], ''),
nullIf(['fixed', 'mobile', 'hosting', 'proxy', 'tor'][network], ''),
nullIf(referrer, ''),
if(endpoint = 2, verified, NULL),
NULL, -- verification_id
NULL, -- error
NULL, -- pow_algorithm
NULL, -- protection_level
NULL, -- his_automation
NULL, -- his_assistive
arrayFilter(r -> r != '', arrayMap(n -> [
'CAPITALIZATION', 'CURRENCY', 'DMARC', 'EMOJI', 'EXCLAMATION', 'FREE_PROVIDER', '',
'HIGH_RISK_COUNTRY', 'HOSTING', '', 'HTML_INJECTION', 'MALICIOUS', 'MX', '', 'PROFANITY',
'PROXY', 'RANDOM_CHARS', '', 'SPAM_WORDS', '', 'SQL_INJECTION', 'TOR', '', '', 'URL', 'BOT',
'ACCEPT_HEADER_MISSING', 'ACCEPT_LANGUAGE_HEADER_MISSING', 'USER_AGENT_HEADER_MISSING',
'DISPOSABLE', 'LOCATION_DISTANCE', 'TIMEZONE_MISMATCH', 'RATE_LIMIT', 'SIMILARITY',
'URL_PHISHING', ''
][n], triggeredRules)),
if(JSONExtractString(context['threats'], 'action') = '', map(),
 map('threatAction', JSONExtractString(context['threats'], 'action')))
FROM altcha_sentinel.logs
WHERE toYYYYMM(time) = {month:UInt32};
```

The reference `logs` table has no `verificationId`, `error`, `powAlgorithm`, `hisScore`, or `hisAssistive` columns, although v1 sent those fields. If `DESCRIBE TABLE altcha_sentinel.logs` lists them, replace the matching `NULL`s:

| Column | Expression |
|---|---|
| `verification_id` | `nullIf(verificationId, '')` |
| `error` | `nullIf(error, '')` |
| `pow_algorithm` | `nullIf(powAlgorithm, '')` |
| `his_automation` | `nullIf(hisScore, 0) / 100` |
| `his_assistive` | `if(ifNull(hisScore, 0) = 0, NULL, hisAssistive)` |

### Step 4 — Run it for every month

```bash
for m in $(clickhouse-client -q "SELECT partition FROM system.parts
WHERE database = 'altcha_sentinel' AND table = 'logs' AND active
GROUP BY partition ORDER BY partition"); do
clickhouse-client --param_month="$m" --queries-file import.sql || break
done
```

To redo a month, empty it first: `ALTER TABLE altcha_sentinel.request_logs_import DROP PARTITION 202611`.

### Step 5 — Compare row counts

Every month should match:

```sql
SELECT month, o.rows AS old_rows, n.rows AS imported_rows
FROM (SELECT toYYYYMM(time) AS month, count() AS rows FROM altcha_sentinel.logs GROUP BY month) AS o
LEFT JOIN (SELECT toYYYYMM(ts) AS month, count() AS rows FROM altcha_sentinel.request_logs_import GROUP BY month) AS n
USING month
ORDER BY month;
```

### Step 6 — Insert into `request_logs`

Insert each month into `request_logs`; v2's own rows stay. Inserting, unlike attaching partitions, runs the rows through the hourly stats. Insert each month **exactly once**, or its rows and stats are doubled:

```sql
INSERT INTO altcha_sentinel.request_logs SELECT * FROM altcha_sentinel.request_logs_import WHERE toYYYYMM(ts) = 202611;
```

Rows older than `[clickhouse] raw_retention` are then deleted from `request_logs`, so they leave search but stay in stats. Stats cover every month only when `request_logs` was created for this import (Step 1), at startup or from the `schema sql --clickhouse` script. Otherwise, rows older than v2's first start aren't in the stats.

### Step 7 — Clean up

```sql
DROP TABLE altcha_sentinel.request_logs_import;
DROP FUNCTION sentinel_b32;
```

### How the rows are converted

- The conversion matches `migrate`. Enum numbers become names, challenge and verify rows get the paths `/v1/challenge` and `/v1/verify`, and `verified` is kept only on verify rows. Classifier rules without an equivalent are dropped. Of `context`, only the threat action is kept, as `threatAction`.
- v1 stored `serverLatency` in microseconds and `hisScore` multiplied by 100; the SQL converts both. IPv4 addresses stored as `::ffff:a.b.c.d` become `a.b.c.d`, and `::` becomes `null`. `userIp` isn't copied.
- Times have second precision. Hourly stats are deleted 5 years after their time.
- If v1's ClickHouse is another server, run the steps on the new one and read the old table with `remoteSecure('old-host:9440', 'altcha_sentinel', 'logs', 'user', 'password')` (or `remote` on port 9000) in place of `altcha_sentinel.logs` in `import.sql` and Step 5. In Step 4, list the partitions on the old server with `clickhouse-client --host old-host …`.

## Verify it works

1. In the v2 admin UI, **Accounts**, **Users**, **API Keys**, and **Security Groups** show your v1 data.
2. A widget key serves challenges:

```bash
curl -s -o /dev/null -w '%{http_code}\n' 'https://sentinel.example.com/v2/challenge?apiKey=key_…'
```

Expect `200`. `403 BEARER_AUTH_PUBLIC_API_KEY` means the key's group isn't `public`; `403 LICENSE_NOT_ACTIVE` means the license isn't active.
3. A backend key authenticates with its v1 secret:

```bash
curl -s https://sentinel.example.com/v2/ip -u 'key_…:sec_…' \
 -H 'Content-Type: application/json' -d '{"ip": "203.0.113.10"}'
```

Expect `{"data": …}`. `500 INTERNAL_ERROR` (with `failed to decrypt stored secret` in the server log) means the snapshot was converted with another `encryption_key`: convert and restore again with the server's secrets.
4. **Logs** shows the migrated request logs, or the copied ClickHouse logs.

## Next steps

- [Upgrade checklist](/docs/sentinel/v2/upgrade/): switch widgets and backends, then cut over.
- [Breaking changes](/docs/sentinel/v2/upgrade/breaking-changes/): API changes for your integrations.
- [Snapshots & backups](/docs/sentinel/v2/operations/snapshots/): schedule v2 snapshots.
