Mapping v1 environment variables to v2 configuration
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 for types, defaults, and ranges.
Prerequisite: read The configuration file 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_FILEsuffix 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.
- 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
/v2API. They come over with Migrating data, not with this mapping.
# 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, 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. |
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.
| v1 env var | v2 TOML key | Notes |
|---|---|---|
ALTCHA_HMAC_SECRET | [secrets] altcha_hmac_secret | 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 | 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 | New. 64 hex characters; encrypts API key secrets and OTP secrets in the database. Losing it makes them unreadable. |
| — | [secrets] vapid_private_key | New. Only for web push alerts ([alerts.push]). |
Licensing
| v1 env var | v2 TOML key | Notes |
|---|---|---|
LICENSE_KEY | [license] key | Use a Sentinel V2 license key (SENT-…) from ALTCHA Cloud. It is activated against https://license.altcha.org ([license] server) and refreshed daily. |
LICENSE_JSON | [license] file | 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.
Application
| v1 env var | v2 TOML key | Notes |
|---|---|---|
PORT | [server] port | Default 3000. The admin UI (3002), widget-only API (3003), and Prometheus (3001) have their own listeners. |
DATA_DIR | data_dir | Top-level key. Relative paths resolve against the working directory (/home/nonroot in the image). |
BASE_URL | [server] base_url | 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 | 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 | 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. |
USER_AGENT | Removed | Outbound requests use a fixed altcha-sentinel/<version> User-Agent. |
API_DOCS_ENABLED | [server.admin_ui] api_reference | Default true. GET /v2/openapi.json is always served. |
INSPECT_ROUTE_ENABLED | [inspect] enabled | 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 | 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] to the internet. |
ALLOWED_HOSTS | 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. The management API sends no CORS headers. |
X_FORWARDED_FOR_TRUSTED | [server] trusted_proxies | 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 | 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 | Default "ALTCHA_SENTINEL". |
JWT_TTL | [auth] jwt_ttl | Default "24h". |
SECURITY_TXT | Removed | v2 serves no /.well-known/security.txt. |
TLS_EXTRA_CA_CERTS | tls_extra_ca_certs | 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 | tls = { cert = "/path/fullchain.pem", key = "/path/privkey.pem" }: file paths, not PEM contents. Set per listener. |
ANONYMIZE_IP_ADDRESS | [privacy] anonymize_ip | 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]] 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 | Trusted like client_ip_header. |
Networking
v2 reads the standard proxy variables from the environment, as v1 did. See Outbound proxy & 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. |
Database
Set one connection URL in [database] url; 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.
TLS options are query parameters of the URL, not separate settings; see 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 | 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. |
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. |
KV store (Redis)
| v1 env var | v2 TOML key | Notes |
|---|---|---|
REDIS_URL | [redis] nodes | 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 | 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 | Several entries are cluster seeds. |
REDIS_KEY_PREFIX | [redis] key_prefix | Default "sentinel:"; must be the same on every replica. |
REDIS_COMMAND_TIMEOUT, REDIS_CONNECT_TIMEOUT | [redis] timeout | 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 | 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 | 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 | 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]. See Snapshots & backups.
| v1 env var | v2 TOML key | Notes |
|---|---|---|
SNAPSHOTS_ENABLED | [snapshots] enabled | Default true. |
SNAPSHOTS_MAIN_SCHEDULE | [snapshots] schedule | 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 | Default "snapshots/". |
SNAPSHOTS_AGE_SECRET_KEY | [snapshots] identity | 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 | Extra recipients (age1…), e.g. an offline recovery key. Needs identity. |
SNAPSHOTS_STORAGE_PROVIDER | [storage] provider | 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] | Separate keys: endpoint, region, bucket, access_key_id, secret_access_key, path_style. |
SNAPSHOTS_STORAGE_AZURE_CONTAINER | [storage.azure] container | |
SNAPSHOTS_STORAGE_AZURE_CONNECTION_STRING | [storage.azure] connection_string |
File storage
| v1 env var | v2 TOML key | Notes |
|---|---|---|
STORAGE_PROVIDER | [storage] provider | 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] | 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 | Default "10s". Changes also reach every replica at once over pub/sub. |
CACHE_DURATION_TRAINING_DATA | [similarity] sync_interval | 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 | 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 | 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. |
REQUEST_LOGS_TTL | [request_logs] retention | 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 ([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.
| v1 env var | v2 TOML key | Notes |
|---|---|---|
MONITORING_IP_WHITELIST | [server] health_allowed_ips for /.health; [prometheus] allowed_ips 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 | 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 | 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.
| v1 env var | v2 TOML key | Notes |
|---|---|---|
CLICKHOUSE_URL | [clickhouse] url, database, username, password | 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 | A duration; default "1s". |
CLICKHOUSE_BATCH_MAX | [request_logs] batch_size | Default 100. |
CLICKHOUSE_TLS_CA | [clickhouse] tls_ca | 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 | 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.
| v1 env var | v2 TOML key | Notes |
|---|---|---|
SSO_AZURE | [auth.oauth.azure] | 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] | client_id, client_secret, and the new required hosted_domain: Google Workspace only. |
SSO_KEYCLOAK | [auth.oauth.keycloak] | client_id, client_secret, and issuer = "https://id.example.com/realms/<realm>" instead of the URL plus realm. |
SSO_OKTA | [auth.oauth.okta] | client_id, client_secret, and issuer, the authorization server URL, e.g. "https://corp.okta.com/oauth2/default". |
SSO_LDAP | [auth.ldap] | One key per URL query option; see 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. |
| v1 env var | v2 TOML key | Notes |
|---|---|---|
SMTP_URL | Removed | It served Forms, which are removed. To email alerts, configure [alerts.email] (host, port, tls, username, password, from, to). |
EML_BODY_LIMIT | [eml] max_body_size | 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] (typesafe or openrouter). Embeddings for similarity are configured in [similarity]. See 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 | file (default) or memory. |
THREATS_MALICIOUS_LIMIT | [threats.signals] malicious | { limit = "10/5m", expire = "48h" } instead of 10/5m(expire=48h). |
THREATS_PROBE_LIMIT | [threats.signals] probe | { 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.
| 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. |
HIGH_RISK_COUNTRIES_EXCLUDE | Removed | List the countries you want in classifier.highRiskCountries. |
PENALTY_TTL | [penalty] ttl | Default "30m" after the last increase. The penalty is now kept per account and client IP. |
[[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.
| v1 env var | v2 TOML key | Notes |
|---|---|---|
PHISHING_LIST_URL | [classifier.phishing] url | 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 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 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 | 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 | Default "10/5m", per client IP. "" means unlimited. |
AUDIO_CHALLENGE_DELAY | [code_challenge] audio_delay | Default "3s". |
POW_MAX_MEMORY | [pow] max_memory_cost | In KiB: 128MB is 131072. Default 262144 (256 MiB). |
POW_MAX_THREADS | [pow] cpus | 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 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: every v2 key with its default.
- Breaking changes: API and behavior changes beyond configuration.
- Upgrade checklist: where configuration fits into the upgrade.