Migrating data from v1
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 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. 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. |
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. |
| 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. |
| Automatic threat entries | v2 creates its own from threat signals. |
| Disabled account features | Access is controlled by roles. |
| 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. |
| Configuration | Environment variables don't migrate. See 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
localsnapshot storage, the file is in thebackupsdirectory of the v1 data directory (/data/backupsin 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:
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 /migrationFor 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. |
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:
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 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.
Step 3 — Restore it in v2
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:
curl -X POST https://sentinel.example.com/v2/snapshots/_restore \
-H 'Authorization: Bearer <root session jwt>' \
--data-binary @migration/sentinel-20261117T091503.512Z-manual.zip{ "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 and Snapshots & backups.
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. |
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. |
rule '…' dropped or setting … dropped (no equivalent) | Rebuild the rule with v2 conditions and settings. See 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.
- Threat sources. Your custom sources are listed next to the new defaults.
- Similarity. Semantic matching needs
[similarity] provider. See Similarity & training data.
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.
Default rules. A group whose rules were only v1's defaults (Autopilot, optionally with the default proof-of-work version rule) becomes:
- a
publicgroup: the Recommended preset (rules namedpreset:recommended:*); - a
restrictedorfullgroup: 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
penaltyrange such as4-10, anipvalue with*, or an unknown field; - a setting without an equivalent (for example
ai), while the rest of the rule is kept; - a
setrule left with no settings; - an
adaptivecode challenge orthreats = truein a rule whose conditions are joined withor; - 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.
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.
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.
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). 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:
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:
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 NULLs:
| 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
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
doneTo 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:
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:
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
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/challengeand/v1/verify, andverifiedis kept only on verify rows. Classifier rules without an equivalent are dropped. Ofcontext, only the threat action is kept, asthreatAction. - v1 stored
serverLatencyin microseconds andhisScoremultiplied by 100; the SQL converts both. IPv4 addresses stored as::ffff:a.b.c.dbecomea.b.c.d, and::becomesnull.userIpisn'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')(orremoteon port 9000) in place ofaltcha_sentinel.logsinimport.sqland Step 5. In Step 4, list the partitions on the old server withclickhouse-client --host old-host ….
Verify it works
In the v2 admin UI, Accounts, Users, API Keys, and Security Groups show your v1 data.
A widget key serves challenges:
curl -s -o /dev/null -w '%{http_code}\n' 'https://sentinel.example.com/v2/challenge?apiKey=key_…'Expect
200.403 BEARER_AUTH_PUBLIC_API_KEYmeans the key's group isn'tpublic;403 LICENSE_NOT_ACTIVEmeans the license isn't active.A backend key authenticates with its v1 secret:
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(withfailed to decrypt stored secretin the server log) means the snapshot was converted with anotherencryption_key: convert and restore again with the server's secrets.Logs shows the migrated request logs, or the copied ClickHouse logs.
Next steps
- Upgrade checklist: switch widgets and backends, then cut over.
- Breaking changes: API changes for your integrations.
- Snapshots & backups: schedule v2 snapshots.