# Mapping v1 environment variables to v2 configuration

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

Sentinel v1 was configured with environment variables; v2 reads one TOML file, `sentinel.toml`. Use this page to translate an existing v1 configuration, one table per v1 topic. Keys are written as `[section] key`; follow the links to the [Configuration reference](/docs/sentinel/v2/reference/configuration/) for types, defaults, and ranges.

Prerequisite: read [The configuration file](/docs/sentinel/v2/configure/) for how the file is loaded. Unknown keys stop startup, so a misspelled key fails fast instead of being ignored.

## How to translate

- **Environment values become TOML values.** Keep secrets out of the file by referencing them: `"${VAR}"` reads an environment variable, `"${VAR:-fallback}"` adds a default, and `"${file:/run/secrets/name}"` reads a mounted secret. This replaces v1's `_FILE` suffix and `${VAR}` expansion inside variables.
- **Most v2 defaults differ from v1.** Don't copy a v1 value just because it was set; check the v2 default first. The ones that bite most often are flagged in [Defaults that changed](#defaults-that-changed).
- **Removed** means v2 has no setting for it. The *Notes* column says why, or what to use instead.
- **Tenant settings aren't in the file.** Accounts, users, API keys, security groups, training data, and threat lists live in the database and are managed in the admin UI or the `/v2` API. They come over with [Migrating data](/docs/sentinel/v2/upgrade/migrate-data/), not with this mapping.

```toml
# v1: PORT=8080, BASE_URL=https://captcha.example.com, X_FORWARDED_FOR_TRUSTED=10.0.0.0/8,
#     POSTGRES_URL=postgres://sentinel:…@db:5432/sentinel, REDIS_URL=redis://redis:6379,
#     JWT_SECRET_FILE=/run/secrets/jwt_secret, LICENSE_KEY=…
[server]
port = 3000
base_url = "https://captcha.example.com"
trusted_proxies = ["10.0.0.0/8"]

[database]
url = "postgres://sentinel:${DB_PASSWORD}@db:5432/sentinel"

[redis]
nodes = ["redis://redis:6379"]

[secrets]
jwt_secret         = "${file:/run/secrets/jwt_secret}"
altcha_hmac_secret = "${file:/run/secrets/altcha_hmac_secret}"
encryption_key     = "${file:/run/secrets/encryption_key}"   # new in v2: 64 hex characters

[license]
key = "${SENTINEL_LICENSE_KEY}"   # a Sentinel V2 license key (SENT-…)
```

## Defaults that changed

| Setting | v1 default | v2 default | What to do |
|---|---|---|---|
| Main port | `8080` in the Docker image | `3000` (`[server] port`) | Update port mappings, load balancer targets, and health checks, or set `port = 8080`. |
| Data directory | `/data` in the Docker image | `./data`, which is `/home/nonroot/data` in the image (`data_dir`) | Mount the data volume at `/home/nonroot/data`. The container runs as uid `65532`. |
| Trusted proxies | Empty `X_FORWARDED_FOR_TRUSTED` trusted every proxy | Empty `[server] trusted_proxies` trusts none: the TCP peer is the client | List your proxies, or every client appears with the proxy's IP. |
| IP anonymization | On (`ANONYMIZE_IP_ADDRESS=1`) | Off (`[privacy] anonymize_ip = false`) | Set `anonymize_ip = true` to keep v1's behavior. |
| Admin UI | Served on the main port | Off; its own listener on `127.0.0.1:3002` (`[server.admin_ui]`) | Set `enabled = true`, and `host` when it must be reachable from outside the container. |
| Root password | `root` | Random, logged once on first start (`[bootstrap] root_password`) | After [restoring a migrated snapshot](/docs/sentinel/v2/upgrade/migrate-data/), the v1 users and passwords apply instead. |
| Redis key prefix | Empty | `"sentinel:"` (`[redis] key_prefix`) | Nothing, unless several deployments share one Redis. |
| Redis timeout | `5s` command, `10s` connect | `2s` for both (`[redis] timeout`) | Raise it only for a slow or distant Redis; a timed-out command counts toward the KV fallback. |
| Log format | `json` (`LOG_FORMAT`) | `text` (`[log] format`) | Set `format = "json"` if a log collector parses the output. |
| Classifier list download limit | `20MB` phishing and user agents, `5MB` disposable domains | `10` MiB for every list (`[classifier.<list>] max_size_mb`) | A self-hosted list over 10 MiB fails to download; raise `max_size_mb`. |
| Disposable domains entry limit | `100000` | No limit (`[classifier.disposable] max_entries`) | Set `max_entries` to cap memory use. |
| Phishing list | PhishTank's feed | ALTCHA directory `phishing.csv.gz` (`[classifier.phishing] url`) | Nothing; a PhishTank CSV URL still works. |
| License | 30-day trial without a key | No trial: the functional API returns `403 LICENSE_NOT_ACTIVE` | Configure a v2 license before cutover; see [Licensing](/docs/sentinel/v2/configure/licensing/). |

## Secrets

v2 has four secrets. With the embedded SQLite database they are generated into `<data_dir>/secrets.json` on first start; with any other database, or more than one replica, set them explicitly. See [Secrets](/docs/sentinel/v2/configure/secrets/).

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `ALTCHA_HMAC_SECRET` | [`[secrets] altcha_hmac_secret`](/docs/sentinel/v2/reference/configuration/#secrets) | At least 24 characters. It now signs only the admin sign-in challenge; widget challenges are signed with the API key's secret. You don't need to reuse the v1 value. |
| `CODE_CHALLENGE_SECRET` | Removed | The code challenge token is encrypted with a key derived from the API key's secret. |
| `JWT_SECRET` | [`[secrets] jwt_secret`](/docs/sentinel/v2/reference/configuration/#secrets) | At least 24 characters. v1 sessions don't carry over; users sign in again. |
| `EXOTDB_HMAC_SECRET` | Removed | v2 has no signed access logs. |
| `HASHING_SALT` | Removed | No setting. |
| `NODE_ID` | `HOSTNAME` environment variable | The node ID of the replica's license instance slot. Keep it stable and unique per replica. |
| `SECRET_SEED` | Removed | Secrets aren't derived from a seed. Set the same `[secrets]` values on every replica. |
| — | [`[secrets] encryption_key`](/docs/sentinel/v2/reference/configuration/#secrets) | New. 64 hex characters; encrypts API key secrets and OTP secrets in the database. Losing it makes them unreadable. |
| — | [`[secrets] vapid_private_key`](/docs/sentinel/v2/reference/configuration/#secrets) | New. Only for web push alerts (`[alerts.push]`). |

## Licensing

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `LICENSE_KEY` | [`[license] key`](/docs/sentinel/v2/reference/configuration/#license) | Use a Sentinel V2 license key (`SENT-…`) from [ALTCHA Cloud](https://cloud.altcha.org/). It is activated against `https://license.altcha.org` (`[license] server`) and refreshed daily. |
| `LICENSE_JSON` | [`[license] file`](/docs/sentinel/v2/reference/configuration/#license) | A path to the license file, not its contents. The file is bound to the deployment ID shown in the admin UI under **License**. |

The license can't be set in the admin UI. See [Licensing](/docs/sentinel/v2/configure/licensing/).

## Application

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `PORT` | [`[server] port`](/docs/sentinel/v2/reference/configuration/#server) | Default `3000`. The admin UI (`3002`), widget-only API (`3003`), and Prometheus (`3001`) have their own listeners. |
| `DATA_DIR` | [`data_dir`](/docs/sentinel/v2/reference/configuration/#top-level) | Top-level key. Relative paths resolve against the working directory (`/home/nonroot` in the image). |
| `BASE_URL` | [`[server] base_url`](/docs/sentinel/v2/reference/configuration/#server) | Its path prefixes the URLs handed to widgets. `[server.public_api]`, `[server.admin_ui]`, and `[auth]` have their own `base_url`. |
| `APP_BASE_PATH` | Path of [`[server.admin_ui] base_url`](/docs/sentinel/v2/reference/configuration/#serveradmin_ui) | E.g. `base_url = "https://example.com/admin"`. Your proxy strips the prefix before forwarding. |
| `DEFAULT_ACCOUNT_NAME` | Removed | The first start creates **Default Account**; rename it in the admin UI. A restored snapshot brings the v1 accounts. |
| `DEFAULT_ROOT_PASSWORD` | [`[bootstrap] root_password`](/docs/sentinel/v2/reference/configuration/#bootstrap) | First start only. At least 8 characters; random and logged when unset. |
| `NODE_NAME` | `HOSTNAME` environment variable | Shown in the cluster view and metrics. |
| `TZ` | Removed | Times are UTC. The daily device key (EDK) rotates at midnight of [`[edk] time_zone`](/docs/sentinel/v2/reference/configuration/#edk). |
| `USER_AGENT` | Removed | Outbound requests use a fixed `altcha-sentinel/<version>` User-Agent. |
| `API_DOCS_ENABLED` | [`[server.admin_ui] api_reference`](/docs/sentinel/v2/reference/configuration/#serveradmin_ui) | Default `true`. `GET /v2/openapi.json` is always served. |
| `INSPECT_ROUTE_ENABLED` | [`[inspect] enabled`](/docs/sentinel/v2/reference/configuration/#inspect) | Default `true`; the route is `GET /v2/inspect`. |

## Security & access

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `APP_IP_WHITELIST` | [`[server.admin_ui] allowed_ips`](/docs/sentinel/v2/reference/configuration/#serveradmin_ui) | Applies to the admin UI listener only. The main `[server]` listener also serves the management API; restrict it at your proxy or firewall, and expose only [`[server.public_api]`](/docs/sentinel/v2/reference/configuration/#serverpublic_api) to the internet. |
| `ALLOWED_HOSTS` | [`allowed_hosts`](/docs/sentinel/v2/reference/configuration/#allowed-hosts) of `[server]`, `[server.public_api]`, `[server.admin_ui]`, `[prometheus]` | A TOML array per listener, nothing inherited: `"a.com,*.a.com"` becomes `allowed_hosts = ["a.com", "*.a.com"]`. `*.domain` matches subdomains only, not `domain`. Entries have no scheme, port, or path. Other hosts get `421`. On the API listeners only `/v2` is checked; `GET /` and `GET /.health` answer any host. |
| `CORS_ORIGINS` | Removed | Widget endpoints allow any origin. Restrict which sites may use a key with `origin` conditions in [security rules](/docs/sentinel/v2/policies/security-rules/). The management API sends no CORS headers. |
| `X_FORWARDED_FOR_TRUSTED` | [`[server] trusted_proxies`](/docs/sentinel/v2/reference/configuration/#server) | Per listener. Empty trusts no proxy (v1: empty trusted all). For a CDN header such as `CF-Connecting-IP`, use `client_ip_header`. |
| `PASSWORD_LOGIN_ENABLED` | [`[auth] password_login`](/docs/sentinel/v2/reference/configuration/#auth) | `false` requires OAuth or LDAP and is enforced for every user, root included. |
| `PASSWORD_MIN_LENGTH` | Removed | Fixed at 8 to 256 characters. |
| `JWT_ISSUER` | [`[auth] jwt_issuer`](/docs/sentinel/v2/reference/configuration/#auth) | Default `"ALTCHA_SENTINEL"`. |
| `JWT_TTL` | [`[auth] jwt_ttl`](/docs/sentinel/v2/reference/configuration/#auth) | Default `"24h"`. |
| `SECURITY_TXT` | Removed | v2 serves no `/.well-known/security.txt`. |
| `TLS_EXTRA_CA_CERTS` | [`tls_extra_ca_certs`](/docs/sentinel/v2/reference/configuration/#top-level) | Top-level key with PEM contents, usually `"${file:/etc/sentinel/extra-ca.pem}"`. Trusted next to the system CA store by every outbound TLS connection: HTTP clients (webhooks, OAuth, remote files, AI APIs, storage, ClickHouse, the license server), OTLP, SMTP, LDAP, the database, Redis, and a remote ExotDB server. A per-connection CA that replaces the system store (`[auth.ldap] tls_ca`, `sslrootcert` or `ssl-ca` in the database URL) replaces these extra CAs too. Oracle doesn't use it. |
| `HTTP2_CERT`, `HTTP2_KEY` | [`[server] tls`](/docs/sentinel/v2/reference/configuration/#listener-tls) | `tls = { cert = "/path/fullchain.pem", key = "/path/privkey.pem" }`: file paths, not PEM contents. Set per listener. |
| `ANONYMIZE_IP_ADDRESS` | [`[privacy] anonymize_ip`](/docs/sentinel/v2/reference/configuration/#privacy) | Default `false` (v1: on). Covers request logs, audit logs, alerts, and log lines; threat entries keep full IPs. |
| `ACCESS_LOG_ANONYMIZE_IP_ADDRESS` | Removed | v2 has no access logs. Logins and management changes go to audit logs, which follow `[privacy] anonymize_ip`. |
| `IP_HEADERS_SECRET` | [`[[ip_resolver.providers]]`](/docs/sentinel/v2/reference/configuration/#ip_resolverproviders) `type = "headers"`, `secret` | The `X-IP-*` headers are an IP resolver provider. |
| `HEADER_ENTROPY_MAX_ENTRIES` | Removed | Header entropy is limited per security group with the `headerEntropy.limit` rule setting. |
| `EDK_SEED_HEADER` | [`[edk] seed_header`](/docs/sentinel/v2/reference/configuration/#edk) | Trusted like `client_ip_header`. |

## Networking

v2 reads the standard proxy variables from the environment, as v1 did. See [Outbound proxy & air-gapped](/docs/sentinel/v2/configure/air-gapped/).

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `HTTP_PROXY`, `HTTPS_PROXY` | Same environment variables | `ALL_PROXY` (including `socks5h://`) is a fallback for both. SMTP, LDAP, and Redis always connect directly. |
| `NO_PROXY` | Same environment variable | Hosts (with subdomains), IPs, CIDRs, or `*`. |
| `HTTPS_PROXY_REJECT_UNAUTHORIZED` | Removed | Certificates are always verified. For a TLS-intercepting proxy, add its CA to [`tls_extra_ca_certs`](/docs/sentinel/v2/reference/configuration/#top-level). |

## Database

Set one connection URL in [`[database] url`](/docs/sentinel/v2/reference/configuration/#database); the scheme selects the backend. Without it, Sentinel uses embedded SQLite at `<data_dir>/sentinel.db`. Backends other than SQLite need the matching `exotdb.backend.<kind>` license feature, such as `exotdb.backend.mariadb`. See [Databases & KV store](/docs/sentinel/v2/configure/databases/).

TLS options are query parameters of the URL, not separate settings; see [Database TLS](/docs/sentinel/v2/reference/configuration/#database-tls). They take file paths, where v1 took PEM contents, so mount the certificates as files. For PostgreSQL, MySQL, MariaDB, and SQL Server, the system CA store, the AWS RDS CA bundle, and `tls_extra_ca_certs` are trusted unless the URL names its own CA.

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `POSTGRES_URL` | `[database] url` | `postgres://user:${DB_PASSWORD}@host:5432/db`. PostgreSQL 16 or later. |
| `MYSQL_URL` | `[database] url` | `mysql://…`. MySQL 8.0.13 or later. A `mysql://` URL refuses a MariaDB server. |
| `MARIADB_URL` | `[database] url` | `mariadb://…`. MariaDB 11.4 LTS or later; older versions stop startup. A `mysql://` URL refuses a MariaDB server, so use the `mariadb://` scheme. Needs the `exotdb.backend.mariadb` license feature. |
| `MSSQL_URL` | `[database] url` | `mssql://…` or `sqlserver://…`. SQL Server 2022 or later. Included in every image. |
| `ORACLE_URL` | `[database] url` | `oracle://…`. Oracle 21c or later. Needs the `-oracle` image tag. |
| `LIBSQL_URL` | Removed | LibSQL/Turso isn't supported. |
| `TURBOLITE_URL` | Removed | Turbolite isn't supported. |
| `DATABASE_URL` | `[database] url` | In v2, an `http(s)://` URL connects to a remote ExotDB server, with `[database] token`, `name`, and `request_timeout` (default `"60s"`). |
| `POSTGRES_MAX_CONNECTIONS`, `MYSQL_MAX_CONNECTIONS`, `MARIADB_MAX_CONNECTIONS`, `MSSQL_MAX_CONNECTIONS`, `ORACLE_MAX_CONNECTIONS` | [`[database] pool_max`](/docs/sentinel/v2/reference/configuration/#database) | Default `20` (v1: `10`). Per replica. |
| `POSTGRES_MIN_CONNECTIONS` | `[database] pool_min` | Default `2` (v1: `0`). Applies to every backend. |
| `POSTGRES_IDLE_TIMEOUT` | `[database] idle_timeout` | A duration, not milliseconds: `10000` is `"10s"`. Default `"10m"` (v1: 10 s). `"0s"` disables, as `0` did. Every backend except SQLite. |
| `POSTGRES_CONNECT_TIMEOUT`, `MYSQL_CONNECT_TIMEOUT`, `MARIADB_CONNECT_TIMEOUT`, `MSSQL_CONNECT_TIMEOUT`, `ORACLE_CONNECT_TIMEOUT` | `[database] acquire_timeout` | The longest wait for a free pooled connection, a duration: `10000` is `"10s"`. Default `"5s"` (v1: 10 s). |
| — | `[database] max_lifetime` | New. Replaces a connection after this long; default `"30m"`. Every backend except SQLite. |
| `LIBSQL_AUTH_TOKEN`, `LIBSQL_MAX_CONNECTIONS` | Removed | LibSQL isn't supported. |
| `POSTGRES_TLS_CA`, `POSTGRES_TLS_CERT`, `POSTGRES_TLS_KEY` (and `POSTGRES_SSL_*`) | `sslrootcert`, `sslcert`, `sslkey` in `[database] url` | E.g. `postgres://…/sentinel?sslmode=verify-full&sslrootcert=/run/secrets/db-ca.pem&sslcert=/run/secrets/db-client.pem&sslkey=/run/secrets/db-client.key`. Without `sslmode`, the driver uses `prefer`: TLS when the server offers it, without certificate verification. Set `verify-full` to verify. |
| `MYSQL_TLS_CA`, `MYSQL_TLS_CERT`, `MYSQL_TLS_KEY`, `MARIADB_TLS_CA`, `MARIADB_TLS_CERT`, `MARIADB_TLS_KEY` | `ssl-ca`, `ssl-cert`, `ssl-key` in `[database] url` | E.g. `mariadb://…/sentinel?ssl-mode=VERIFY_IDENTITY&ssl-ca=/run/secrets/db-ca.pem`. Without `ssl-mode`, the driver uses `PREFERRED`: TLS when the server offers it, without certificate verification. Set `VERIFY_IDENTITY` (or `VERIFY_CA`) to verify. |
| `MYSQL_TLS_REJECT_UNAUTHORIZED`, `MARIADB_TLS_REJECT_UNAUTHORIZED` | `ssl-mode` in `[database] url` | `0` becomes `ssl-mode=REQUIRED` (TLS without verification); `1` becomes `VERIFY_IDENTITY`. |
| `MSSQL_TLS_CA` | `trust_cert_ca` in `[database] url` | SQL Server connections are encrypted and verified by default. `trust_cert_ca=/run/secrets/db-ca.pem` trusts a CA file; `encrypt=false` turns TLS off. |
| `MSSQL_TLS_REJECT_UNAUTHORIZED` | `trust_cert` in `[database] url` | `0` becomes `trust_cert=true` (no verification). Can't be combined with `trust_cert_ca`. |
| `MSSQL_TLS_CERT`, `MSSQL_TLS_KEY` | Removed | No client certificates for SQL Server. |
| `ORACLE_TLS_CA` | `tcps` connect string, plus a wallet for a private CA | The connect string after `@` goes to Oracle Instant Client unchanged. A server certificate from a public CA needs only `tcps://host:2484/service?ssl_server_dn_match=true`. A private CA goes into an auto-login wallet (`cwallet.sso`, built with `orapki`) that you mount and name with `wallet_location`. `tls_extra_ca_certs` doesn't apply, and the AWS RDS CA bundle isn't added for Oracle as v1 did. See [Oracle TLS](/docs/sentinel/v2/reference/configuration/#oracle-tls). |
| `ORACLE_TLS_REJECT_UNAUTHORIZED` | Removed | Oracle Net verifies a `tcps` server certificate against the wallet, or the image's system CA bundle without one. |
| `EXOTDB_DATABASE_ADDR`, `EXOTDB_ROOT_PASSWORD` | Removed | The embedded database runs in-process and opens no port. |
| `EXOTDB_DATABASE_LOCATION` | `[database] url` | `url = "sqlite:/path/to/sentinel.db"`. Default `sqlite:<data_dir>/sentinel.db`. |
| `EXOTDB_ENCRYPTION_KEY` | Removed | The database file isn't encrypted. Secrets inside it are encrypted with `[secrets] encryption_key`. |
| `CLUSTER_ELECTOR_S3_URL`, `CLUSTER_ADVERTISE_HTTP_ADDR`, `CLUSTER_ADVERTISE_REDIS_ADDR` | Removed | No leader election over S3. Run several replicas on a shared database and Redis; see [Clustering](/docs/sentinel/v2/operations/clustering/). |

## KV store (Redis)

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `REDIS_URL` | [`[redis] nodes`](/docs/sentinel/v2/reference/configuration/#redis) | A list: `nodes = ["redis://host:6379"]`. Empty (the default) uses the built-in KV store in the Sentinel database, for a single node only. Redis 6.2 or later. For TLS, see the next row. |
| — | [`[redis] tls_ca`, `tls_cert`, `tls_key`](/docs/sentinel/v2/reference/configuration/#redis) | New. `rediss://` nodes connect over TLS and verify against the system CA store, `tls_extra_ca_certs`, and `tls_ca` (PEM contents). `tls_cert` and `tls_key` present a client certificate. Append `#insecure` to a node URL (`rediss://host:6380/#insecure`) to skip verification. The `tls_*` keys need every node to be `rediss://`. |
| `REDIS_CLUSTER_URL` | [`[redis] nodes`](/docs/sentinel/v2/reference/configuration/#redis) | Several entries are cluster seeds. |
| `REDIS_KEY_PREFIX` | [`[redis] key_prefix`](/docs/sentinel/v2/reference/configuration/#redis) | Default `"sentinel:"`; must be the same on every replica. |
| `REDIS_COMMAND_TIMEOUT`, `REDIS_CONNECT_TIMEOUT` | [`[redis] timeout`](/docs/sentinel/v2/reference/configuration/#redis) | One duration for connecting and for each command, default `"2s"` (v1: `5000` and `10000` ms). Milliseconds become a duration: `5000` is `"5s"`. |
| `REDIS_MAX_RETRIES` | Removed | No setting. |
| `REDIS_SENTINEL_HOSTS` | [`[redis.sentinel] nodes`](/docs/sentinel/v2/reference/configuration/#redissentinel) | URLs instead of `host:port`: `s1:26379,s2:26379` becomes `nodes = ["redis://s1:26379", "redis://s2:26379"]`. `[redis] nodes` must be empty. |
| `REDIS_SENTINEL_MASTER_NAME` | [`[redis.sentinel] master`](/docs/sentinel/v2/reference/configuration/#redissentinel) | Required. |
| `REDIS_SENTINEL_AUTH` | Userinfo of each `[redis.sentinel] nodes` URL | `redis://user:password@s1:26379`, or `redis://:password@s1:26379` without a user; percent-encode reserved characters. It must be the same on every entry. |
| `REDIS_SENTINEL_REDIS_AUTH` | [`[redis.sentinel] username`, `password`](/docs/sentinel/v2/reference/configuration/#redissentinel) | Credentials for the master. |
| `REDIS_SENTINEL_TLS`, `REDIS_SENTINEL_REDIS_TLS` | `rediss://` in `[redis.sentinel] nodes` | One switch for both: `rediss://` Sentinel URLs also connect to the master over TLS, so TLS to only one side isn't possible. `[redis] tls_ca`, `tls_cert`, `tls_key`, and `#insecure` apply to both. |
| `EXOTDB_REDIS_ADDR`, `EXOTDB_REDIS_STORAGE`, `EXOTDB_REDIS_LOCATION`, `TURBOLITE_REDIS_URL` | Removed | The built-in KV store lives in the Sentinel database and opens no port. |

## Snapshots

v2 snapshots cover the main database only and are stored in the shared [`[storage]`](/docs/sentinel/v2/reference/configuration/#storage). See [Snapshots & backups](/docs/sentinel/v2/operations/snapshots/).

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `SNAPSHOTS_ENABLED` | [`[snapshots] enabled`](/docs/sentinel/v2/reference/configuration/#snapshots) | Default `true`. |
| `SNAPSHOTS_MAIN_SCHEDULE` | [`[snapshots] schedule`](/docs/sentinel/v2/reference/configuration/#snapshots) | Cron, UTC. Needs `[snapshots] identity` and a `[storage]` provider. `keep` sets how many scheduled snapshots are kept (default `7`). |
| `SNAPSHOTS_REDIS_SCHEDULE` | Removed | The KV store isn't snapshotted. |
| `SNAPSHOTS_KEY_PREFIX` | [`[snapshots] storage_prefix`](/docs/sentinel/v2/reference/configuration/#snapshots) | Default `"snapshots/"`. |
| `SNAPSHOTS_AGE_SECRET_KEY` | [`[snapshots] identity`](/docs/sentinel/v2/reference/configuration/#snapshots) | An age X25519 identity (`AGE-SECRET-KEY-1…`). When set, snapshots are encrypted to it and can be stored. |
| `SNAPSHOTS_AGE_PUBLIC_KEY` | [`[snapshots] recipients`](/docs/sentinel/v2/reference/configuration/#snapshots) | Extra recipients (`age1…`), e.g. an offline recovery key. Needs `identity`. |
| `SNAPSHOTS_STORAGE_PROVIDER` | [`[storage] provider`](/docs/sentinel/v2/reference/configuration/#storage) | `s3` or `azure`; `local` is removed. One storage serves snapshots and EML attachments; separate them with `[snapshots] storage_prefix` and `[eml] storage_prefix`. |
| `SNAPSHOTS_STORAGE_LOCAL_DIR` | Removed | No local storage. Without `[storage]`, **Create snapshot** downloads the file instead. |
| `SNAPSHOTS_STORAGE_S3_URL` | [`[storage.s3]`](/docs/sentinel/v2/reference/configuration/#storages3) | Separate keys: `endpoint`, `region`, `bucket`, `access_key_id`, `secret_access_key`, `path_style`. |
| `SNAPSHOTS_STORAGE_AZURE_CONTAINER` | [`[storage.azure] container`](/docs/sentinel/v2/reference/configuration/#storageazure) | |
| `SNAPSHOTS_STORAGE_AZURE_CONNECTION_STRING` | [`[storage.azure] connection_string`](/docs/sentinel/v2/reference/configuration/#storageazure) | |

## File storage

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `STORAGE_PROVIDER` | [`[storage] provider`](/docs/sentinel/v2/reference/configuration/#storage) | `s3`, `azure`, or `none` (default). `local` is removed. |
| `STORAGE_LOCAL_DIR` | Removed | No local storage. Below `X-Attachments-Size-Limit`, EML attachments are returned inline. |
| `STORAGE_S3_URL` | [`[storage.s3]`](/docs/sentinel/v2/reference/configuration/#storages3) | No URL form; use the separate keys below. |
| `STORAGE_S3_BUCKET` | `[storage.s3] bucket` | |
| `STORAGE_S3_ACCESS_KEY_ID` | `[storage.s3] access_key_id` | No automatic `AWS_ACCESS_KEY_ID` fallback; write `"${AWS_ACCESS_KEY_ID}"`. |
| `STORAGE_S3_SECRET_ACCESS_KEY` | `[storage.s3] secret_access_key` | No automatic fallback; write `"${AWS_SECRET_ACCESS_KEY}"`. |
| `STORAGE_S3_REGION` | `[storage.s3] region` | |
| `STORAGE_S3_ENDPOINT` | `[storage.s3] endpoint` | For S3-compatible services. Add `path_style = true` for MinIO and similar. |
| `STORAGE_AZURE_CONTAINER` | `[storage.azure] container` | |
| `STORAGE_AZURE_CONNECTION_STRING` | `[storage.azure] connection_string` | |
| `STORAGE_BLOBS_DOWNLOAD_API_ENABLED` | Removed | `/v1/blobs` is gone. `attachments[].contentUri` is the object's native URI; fetch it with your storage credentials. |

## Caching

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `CACHE_DURATION_API_KEYS` | [`[api_key_cache] refresh_interval`](/docs/sentinel/v2/reference/configuration/#api_key_cache) | Default `"10s"`. Changes also reach every replica at once over pub/sub. |
| `CACHE_DURATION_TRAINING_DATA` | [`[similarity] sync_interval`](/docs/sentinel/v2/reference/configuration/#similarity) | Default `"5m"`; a fallback re-read, since changes apply over pub/sub. |
| `CACHE_DURATION_USED_CHALLENGES` | Removed | A used payload is remembered in the KV store until it expires. |

## Logging

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `LOG_LEVEL` | [`[log] level`](/docs/sentinel/v2/reference/configuration/#log) | A filter directive, e.g. `"info"` or `"info,sentinel::http=debug"`. `fatal` and `silent` don't exist; use `"error"` or `"off"`. |
| `LOG_FORMAT` | [`[log] format`](/docs/sentinel/v2/reference/configuration/#log) | `json` or `text` (v1: `plain`). Default `"text"` (v1: `json`). v2 JSON lines have `timestamp`, `level` (e.g. `"INFO"`), `target`, `message`, the event's other fields, and `span`/`spans`; check log parsers and queries against them. <!-- VERIFY: v1 JSON log field names (to state exactly which fields changed) --> |
| `REQUEST_LOGS_TTL` | [`[request_logs] retention`](/docs/sentinel/v2/reference/configuration/#request_logs) | Default `"72h"`, at least `"2h"`. Hourly stats are kept. With ClickHouse, use `[clickhouse] raw_retention`. |
| `ACCESS_LOG_ENABLED` | Removed | No access logs. See [Audit logs](/docs/sentinel/v2/operations/audit-logs/) (`[audit_logs]`). |

## Monitoring

`/.live`, `/.ready`, `/v1/ping`, `/.logs`, and `/.metrics` are gone. Liveness and readiness are `GET /` on the main listener, and metrics have their own listener. `GET /.health` stays on the main listener with `kv`, `db`, and `clickhouse` checks. See [Health endpoint](/docs/sentinel/v2/reference/configuration/#health-endpoint).

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `MONITORING_IP_WHITELIST` | [`[server] health_allowed_ips`](/docs/sentinel/v2/reference/configuration/#health-endpoint) for `/.health`; [`[prometheus] allowed_ips`](/docs/sentinel/v2/reference/configuration/#prometheus) for metrics | `health_allowed_ips` matches the resolved client IP; default private networks, `[]` allows any client. `[prometheus] allowed_ips` matches the TCP peer; default empty (any). The Prometheus listener is off by default and binds to `127.0.0.1:3001` when enabled. |
| `MONITORING_HTTP_CREDENTIALS` | [`[prometheus] bearer_token`](/docs/sentinel/v2/reference/configuration/#prometheus) | For metrics only: a Bearer token instead of Basic `user:password`. `/.health` has no credentials; restrict it with `health_allowed_ips`. |

## OpenTelemetry

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `OTEL_EXPORTER_OTLP_ENDPOINT` | [`[telemetry] endpoint`](/docs/sentinel/v2/reference/configuration/#telemetry) | Set `[telemetry] enabled = true` too. Without `endpoint`, the standard `OTEL_EXPORTER_OTLP_*` variables are read. Traces only. |
| `OTEL_SERVICE_NAME` | `[telemetry] service_name` | Default `"altcha-sentinel"`. |
| `OTEL_EXPORTER_OTLP_HEADERS` | `[telemetry] headers` | A TOML table, e.g. `{ authorization = "Bearer ${OTEL_TOKEN}" }`. |
| `OTEL_EXPORTER_OTLP_TIMEOUT` | `[telemetry] timeout` | A duration (`"10s"`), not milliseconds; `1s` to `60s`. |

## ClickHouse

Request logs go to a new `request_logs` table. To bring old logs over, see [Copy ClickHouse request logs](/docs/sentinel/v2/upgrade/migrate-data/#copy-clickhouse-request-logs).

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `CLICKHOUSE_URL` | [`[clickhouse] url`, `database`, `username`, `password`](/docs/sentinel/v2/reference/configuration/#clickhouse) | Split the URL: `http://user:pass@host:8123/altcha_sentinel` becomes `url = "http://host:8123"`, `username = "user"`, `password = "${CLICKHOUSE_PASSWORD}"`, `database = "altcha_sentinel"`. Needs the `clickhouse` license feature. |
| `CLICKHOUSE_BATCH_INTERVAL` | [`[request_logs] flush_interval`](/docs/sentinel/v2/reference/configuration/#request_logs) | A duration; default `"1s"`. |
| `CLICKHOUSE_BATCH_MAX` | [`[request_logs] batch_size`](/docs/sentinel/v2/reference/configuration/#request_logs) | Default `100`. |
| `CLICKHOUSE_TLS_CA` | [`[clickhouse] tls_ca`](/docs/sentinel/v2/reference/configuration/#clickhouse) | PEM contents as in v1, e.g. `"${file:/etc/sentinel/clickhouse-ca.pem}"`. Trusted next to the system CA store and `tls_extra_ca_certs`. Needs an `https://` url. |
| `CLICKHOUSE_TLS_CERT`, `CLICKHOUSE_TLS_KEY` | [`[clickhouse] tls_cert`, `tls_key`](/docs/sentinel/v2/reference/configuration/#clickhouse) | PEM contents as in v1; set both. Needs an `https://` url. |

## SSO

Each provider is a table; it is enabled when the table is present. OAuth needs the `oauth` license feature and LDAP the `ldap` feature. Register the new OAuth redirect URI `{base_url}/v2/auth/oauth/{provider}/callback` at each provider. See [Admin sign-in & SSO](/docs/sentinel/v2/security/sign-in/).

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `SSO_AZURE` | [`[auth.oauth.azure]`](/docs/sentinel/v2/reference/configuration/#authoauthazure) | `clientId` → `client_id`, `clientSecret` → `client_secret`, `tenantId` → `tenant_id`. `tenant_id` must be the directory GUID; `common` and `organizations` stop startup. Existing `azure:` users still match. |
| `SSO_GOOGLE` | [`[auth.oauth.google]`](/docs/sentinel/v2/reference/configuration/#authoauthgoogle) | `client_id`, `client_secret`, and the new required `hosted_domain`: Google Workspace only. |
| `SSO_KEYCLOAK` | [`[auth.oauth.keycloak]`](/docs/sentinel/v2/reference/configuration/#authoauthkeycloak) | `client_id`, `client_secret`, and `issuer = "https://id.example.com/realms/<realm>"` instead of the URL plus `realm`. |
| `SSO_OKTA` | [`[auth.oauth.okta]`](/docs/sentinel/v2/reference/configuration/#authoauthokta) | `client_id`, `client_secret`, and `issuer`, the authorization server URL, e.g. `"https://corp.okta.com/oauth2/default"`. <!-- VERIFY: which issuer v1 used for Okta (org vs default authorization server) --> |
| `SSO_LDAP` | [`[auth.ldap]`](/docs/sentinel/v2/reference/configuration/#authldap) | One key per URL query option; see [LDAP options](#ldap-options). |
| `SSO_LDAP_TLS_CA`, `SSO_LDAP_TLS_CERT`, `SSO_LDAP_TLS_KEY` (and `SSO_LDAP_SSL_*`, `*_FILE`) | `[auth.ldap] tls_ca`, `tls_cert`, `tls_key` | PEM inline, or `"${file:/path}"`. |

### LDAP options

v2 reads explicit `[auth.ldap]` keys. A query string, credentials, or a path in `url` stops startup, and so does a camelCase key.

| `SSO_LDAP` part | `[auth.ldap]` key | Notes |
|---|---|---|
| Scheme, host, port | `url` | `ldap://` or `ldaps://` with `host[:port]` only. |
| `name` | `name` | Button label. |
| `userDn` | `user_dn` | A value containing `USERNAME` is a full bind-DN template. |
| `usernameAttribute` | `username_attribute` | |
| `username` | `username_template` | |
| `adminDn`, `adminPassword` | `admin_dn`, `admin_password` | Search-then-bind. Use `"${LDAP_ADMIN_PASSWORD}"` for the password. |
| `userSearchBase` | `user_search_base` | |
| `starttls=true` | `starttls = true` | Now also applies the TLS options. |
| `rejectUnauthorized=false` | `reject_unauthorized = false` | Now also applies to StartTLS. |
| `groupClass`, `groupMemberAttribute`, `groupMemberUserAttribute` | `group_class`, `group_member_attribute`, `group_member_user_attribute` | Now enforced, together with the new `group_search_base` and `allowed_groups`. |
| `ALLOW_LDAP` | Removed | LDAP is on when `[auth.ldap]` is present. |

## Email

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `SMTP_URL` | Removed | It served Forms, which are removed. To email alerts, configure [`[alerts.email]`](/docs/sentinel/v2/reference/configuration/#alertsemail) (`host`, `port`, `tls`, `username`, `password`, `from`, `to`). |
| `EML_BODY_LIMIT` | [`[eml] max_body_size`](/docs/sentinel/v2/reference/configuration/#eml) | In bytes; default `5000000`. |

## AI providers

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `AI_PROVIDER`, `AI_PROVIDER_MODEL`, `AI_PROVIDER_OPTIONS`, `AI_PROVIDER_REQUEST_OPTIONS` | Removed | AI security rules are replaced by the AI decider, configured in [`[classifier.ai]`](/docs/sentinel/v2/reference/configuration/#classifierai) (`typesafe` or `openrouter`). Embeddings for similarity are configured in [`[similarity]`](/docs/sentinel/v2/reference/configuration/#similarity). See [AI decider](/docs/sentinel/v2/features/ai-decider/). |
| `CONTEXT_DATA_KEY` | Removed | v2 has no context override. |

## Threat intelligence

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `THREATS_ENABLED` | Removed | Threat intelligence is always on. `[threats] seed_defaults = false` skips the default sources on first start; `[threats.signals] enabled = false` stops automatic entries. |
| `THREATS_INDEX_STORE` | [`[threats] store`](/docs/sentinel/v2/reference/configuration/#threats) | `file` (default) or `memory`. |
| `THREATS_MALICIOUS_LIMIT` | [`[threats.signals] malicious`](/docs/sentinel/v2/reference/configuration/#threatssignals) | `{ limit = "10/5m", expire = "48h" }` instead of `10/5m(expire=48h)`. |
| `THREATS_PROBE_LIMIT` | [`[threats.signals] probe`](/docs/sentinel/v2/reference/configuration/#threatssignals) | `{ limit = "2/5m", expire = "48h" }`. |
| `THREATS_BOT_LIMIT`, `THREATS_PROXY_LIMIT`, `THREATS_TOR_LIMIT` | Removed | Only `malicious` and `probe` signals create automatic entries. |

## Geolocation & risk detection

v2 looks up IPs only through the providers you list in `[[ip_resolver.providers]]`, in priority order. Without one, requests have no country or network type. See [IP resolvers](/docs/sentinel/v2/configure/ip-resolvers/).

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `CLOUDFLARE_IP_COUNTRY_ENABLED` | `[[ip_resolver.providers]]` `type = "cloudflare"` | Only expose the server through Cloudflare. |
| `IP_API_COM_TOKEN` | `[[ip_resolver.providers]]` `type = "ip-api"`, `key` | Without `key`, the free HTTP endpoint is used. |
| `IPINFO_IO_TOKEN` | `[[ip_resolver.providers]]` `type = "ipinfo"`, `token` | |
| `IPINFO_IO_LITE_ENABLED` | `[[ip_resolver.providers]]` `type = "ipinfo"`, `api` | `"lite"` (default), `"lookup"`, or `"legacy"`. |
| `IPSTACK_COM_TOKEN` | `[[ip_resolver.providers]]` `type = "ipstack"`, `key` | |
| `IPINFO_IO_MMDB_DOWNLOAD_URL` | `[[ip_resolver.providers]]` `type = "ipinfo-mmdb"`, `url` | Pass the API token in `token`, not in the URL. |
| `IPINFO_IO_MMDB_DOWNLOAD_SCHEDULE`, `IPINFO_IO_MMDB_DOWNLOAD_HEADERS` | `schedule`, `headers` of that provider | |
| `MAXMIND_ACCOUNT_ID`, `MAXMIND_LICENSE_KEY` | `[[ip_resolver.providers]]` `type = "maxmind"`, `account_id`, `license_key` | |
| `MAXMIND_DOWNLOAD_URL` | `url` of the `maxmind` provider | No default: set the download URL, or a local `path` to an `.mmdb` file. |
| `MAXMIND_DOWNLOAD_SCHEDULE`, `MAXMIND_DOWNLOAD_HEADERS` | `schedule`, `headers` of the `maxmind` provider | |
| `HIGH_RISK_COUNTRIES` | Security-group setting `classifier.highRiskCountries` | Per security group, not server-wide. The default list `high_risk` has the same 19 countries as v1. See [Rules reference](/docs/sentinel/v2/reference/rules/#classifier). |
| `HIGH_RISK_COUNTRIES_EXCLUDE` | Removed | List the countries you want in `classifier.highRiskCountries`. |
| `PENALTY_TTL` | [`[penalty] ttl`](/docs/sentinel/v2/reference/configuration/#penalty) | Default `"30m"` after the last increase. The penalty is now kept per account and client IP. |

```toml
[[ip_resolver.providers]]
type        = "maxmind"
name        = "geolite2-city"
url         = "https://download.maxmind.com/geoip/databases/GeoLite2-City/download?suffix=tar.gz"
account_id  = "${MAXMIND_ACCOUNT_ID}"
license_key = "${file:/run/secrets/maxmind_license_key}"
schedule    = "@daily"
```

## Lists

Each list is a remote file with its own `enabled`, `url`, and `schedule`. See [Remote files & data sources](/docs/sentinel/v2/configure/remote-files/).

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `PHISHING_LIST_URL` | [`[classifier.phishing] url`](/docs/sentinel/v2/reference/configuration/#classifier-lists) | Default is the ALTCHA directory's `phishing.csv.gz`. A PhishTank CSV still works. |
| `PHISHING_LIST_SCHEDULE` | `[classifier.phishing] schedule` | Default `"@daily"`. |
| `EMAIL_LIST_DISPOSABLE` | `[classifier.disposable] url` | |
| `EMAIL_LIST_DISPOSABLE_SCHEDULE` | `[classifier.disposable] schedule` | |
| `USER_AGENT_LIST_URL` | `[classifier.user_agents] url` | A CSV with the columns `user_agent,weight` and a header row. |
| `USER_AGENT_LIST_SCHEDULE` | `[classifier.user_agents] schedule` | |
| `PHISHING_LIST_SIZE_LIMIT`, `EMAIL_LIST_DISPOSABLE_SIZE_LIMIT`, `USER_AGENT_LIST_SIZE_LIMIT` | [`max_size_mb`](/docs/sentinel/v2/reference/configuration/#classifier-lists) of `[classifier.phishing]`, `[classifier.disposable]`, `[classifier.user_agents]` | Whole MiB: `20MB` becomes `20`. Default `10` for every list (v1: `20MB`, `5MB`, `20MB`). Counted before extraction. |
| `PHISHING_LIST_MAX_ENTRIES`, `EMAIL_LIST_DISPOSABLE_MAX_ENTRIES`, `USER_AGENT_LIST_MAX_ENTRIES` | [`max_entries`](/docs/sentinel/v2/reference/configuration/#classifier-lists) of the same tables | Defaults: phishing `100000` and user agents `10000`, as in v1; disposable domains no limit (v1: `100000`). The other lists and `[eml.malicious_hashes]` take the same keys. |

## Rate limiting & proof-of-work

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `FLOOD_RATE_LIMIT` | [`[rate_limit] global`](/docs/sentinel/v2/reference/configuration/#rate_limit) | Default `"100/1m"`. Disable with `[rate_limit] enabled = false`, not an empty value. |
| `FLOOD_RATE_LIMIT_KEY` | Removed | The global limit is always per client IP. Per-device or per-user limits are security-group rules (`rateLimit.limits`). |
| `AUDIO_CHALLENGE_RATE_LIMIT` | [`[code_challenge] audio_rate_limit`](/docs/sentinel/v2/reference/configuration/#code_challenge) | Default `"10/5m"`, per client IP. `""` means unlimited. |
| `AUDIO_CHALLENGE_DELAY` | [`[code_challenge] audio_delay`](/docs/sentinel/v2/reference/configuration/#code_challenge) | Default `"3s"`. |
| `POW_MAX_MEMORY` | [`[pow] max_memory_cost`](/docs/sentinel/v2/reference/configuration/#pow) | In KiB: `128MB` is `131072`. Default `262144` (256 MiB). |
| `POW_MAX_THREADS` | [`[pow] cpus`](/docs/sentinel/v2/reference/configuration/#pow) | Default: half the available CPUs. |

## Spam handling

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `DELETE_SPAM_SUBMISSIONS_IN` | Removed | Form submissions are removed with Forms. |

## Container resource limits

| v1 env var | v2 TOML key | Notes |
|---|---|---|
| `CONTAINER_CPUS` | Removed | Set [`[pow] cpus`](/docs/sentinel/v2/reference/configuration/#pow) to cap proof-of-work derivations. |
| `CONTAINER_MEMORY_LIMIT_MB` | Removed | The memory alert reads the cgroup limit itself. |
| `HEAP_LIMIT_MB` | Removed | v2 isn't a Node.js process; there is no heap to size. |

## Related

- [Configuration reference](/docs/sentinel/v2/reference/configuration/): every v2 key with its default.
- [Breaking changes](/docs/sentinel/v2/upgrade/breaking-changes/): API and behavior changes beyond configuration.
- [Upgrade checklist](/docs/sentinel/v2/upgrade/): where configuration fits into the upgrade.
