Skip to main content
ALTCHA®

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 _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.
  • 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, 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

Settingv1 defaultv2 defaultWhat to do
Main port8080 in the Docker image3000 ([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 proxiesEmpty X_FORWARDED_FOR_TRUSTED trusted every proxyEmpty [server] trusted_proxies trusts none: the TCP peer is the clientList your proxies, or every client appears with the proxy's IP.
IP anonymizationOn (ANONYMIZE_IP_ADDRESS=1)Off ([privacy] anonymize_ip = false)Set anonymize_ip = true to keep v1's behavior.
Admin UIServed on the main portOff; 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 passwordrootRandom, logged once on first start ([bootstrap] root_password)After restoring a migrated snapshot, the v1 users and passwords apply instead.
Redis key prefixEmpty"sentinel:" ([redis] key_prefix)Nothing, unless several deployments share one Redis.
Redis timeout5s command, 10s connect2s for both ([redis] timeout)Raise it only for a slow or distant Redis; a timed-out command counts toward the KV fallback.
Log formatjson (LOG_FORMAT)text ([log] format)Set format = "json" if a log collector parses the output.
Classifier list download limit20MB phishing and user agents, 5MB disposable domains10 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 limit100000No limit ([classifier.disposable] max_entries)Set max_entries to cap memory use.
Phishing listPhishTank's feedALTCHA directory phishing.csv.gz ([classifier.phishing] url)Nothing; a PhishTank CSV URL still works.
License30-day trial without a keyNo trial: the functional API returns 403 LICENSE_NOT_ACTIVEConfigure 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 varv2 TOML keyNotes
ALTCHA_HMAC_SECRET[secrets] altcha_hmac_secretAt 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_SECRETRemovedThe code challenge token is encrypted with a key derived from the API key's secret.
JWT_SECRET[secrets] jwt_secretAt least 24 characters. v1 sessions don't carry over; users sign in again.
EXOTDB_HMAC_SECRETRemovedv2 has no signed access logs.
HASHING_SALTRemovedNo setting.
NODE_IDHOSTNAME environment variableThe node ID of the replica's license instance slot. Keep it stable and unique per replica.
SECRET_SEEDRemovedSecrets aren't derived from a seed. Set the same [secrets] values on every replica.
—[secrets] encryption_keyNew. 64 hex characters; encrypts API key secrets and OTP secrets in the database. Losing it makes them unreadable.
—[secrets] vapid_private_keyNew. Only for web push alerts ([alerts.push]).

Licensing

v1 env varv2 TOML keyNotes
LICENSE_KEY[license] keyUse 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] fileA 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 varv2 TOML keyNotes
PORT[server] portDefault 3000. The admin UI (3002), widget-only API (3003), and Prometheus (3001) have their own listeners.
DATA_DIRdata_dirTop-level key. Relative paths resolve against the working directory (/home/nonroot in the image).
BASE_URL[server] base_urlIts path prefixes the URLs handed to widgets. [server.public_api], [server.admin_ui], and [auth] have their own base_url.
APP_BASE_PATHPath of [server.admin_ui] base_urlE.g. base_url = "https://example.com/admin". Your proxy strips the prefix before forwarding.
DEFAULT_ACCOUNT_NAMERemovedThe first start creates Default Account; rename it in the admin UI. A restored snapshot brings the v1 accounts.
DEFAULT_ROOT_PASSWORD[bootstrap] root_passwordFirst start only. At least 8 characters; random and logged when unset.
NODE_NAMEHOSTNAME environment variableShown in the cluster view and metrics.
TZRemovedTimes are UTC. The daily device key (EDK) rotates at midnight of [edk] time_zone.
USER_AGENTRemovedOutbound requests use a fixed altcha-sentinel/<version> User-Agent.
API_DOCS_ENABLED[server.admin_ui] api_referenceDefault true. GET /v2/openapi.json is always served.
INSPECT_ROUTE_ENABLED[inspect] enabledDefault true; the route is GET /v2/inspect.

Security & access

v1 env varv2 TOML keyNotes
APP_IP_WHITELIST[server.admin_ui] allowed_ipsApplies 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_HOSTSallowed_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_ORIGINSRemovedWidget 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_proxiesPer 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_loginfalse requires OAuth or LDAP and is enforced for every user, root included.
PASSWORD_MIN_LENGTHRemovedFixed at 8 to 256 characters.
JWT_ISSUER[auth] jwt_issuerDefault "ALTCHA_SENTINEL".
JWT_TTL[auth] jwt_ttlDefault "24h".
SECURITY_TXTRemovedv2 serves no /.well-known/security.txt.
TLS_EXTRA_CA_CERTStls_extra_ca_certsTop-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] tlstls = { cert = "/path/fullchain.pem", key = "/path/privkey.pem" }: file paths, not PEM contents. Set per listener.
ANONYMIZE_IP_ADDRESS[privacy] anonymize_ipDefault false (v1: on). Covers request logs, audit logs, alerts, and log lines; threat entries keep full IPs.
ACCESS_LOG_ANONYMIZE_IP_ADDRESSRemovedv2 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", secretThe X-IP-* headers are an IP resolver provider.
HEADER_ENTROPY_MAX_ENTRIESRemovedHeader entropy is limited per security group with the headerEntropy.limit rule setting.
EDK_SEED_HEADER[edk] seed_headerTrusted like client_ip_header.

Networking

v2 reads the standard proxy variables from the environment, as v1 did. See Outbound proxy & air-gapped.

v1 env varv2 TOML keyNotes
HTTP_PROXY, HTTPS_PROXYSame environment variablesALL_PROXY (including socks5h://) is a fallback for both. SMTP, LDAP, and Redis always connect directly.
NO_PROXYSame environment variableHosts (with subdomains), IPs, CIDRs, or *.
HTTPS_PROXY_REJECT_UNAUTHORIZEDRemovedCertificates 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 varv2 TOML keyNotes
POSTGRES_URL[database] urlpostgres://user:${DB_PASSWORD}@host:5432/db. PostgreSQL 16 or later.
MYSQL_URL[database] urlmysql://…. MySQL 8.0.13 or later. A mysql:// URL refuses a MariaDB server.
MARIADB_URL[database] urlmariadb://…. 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] urlmssql://… or sqlserver://…. SQL Server 2022 or later. Included in every image.
ORACLE_URL[database] urloracle://…. Oracle 21c or later. Needs the -oracle image tag.
LIBSQL_URLRemovedLibSQL/Turso isn't supported.
TURBOLITE_URLRemovedTurbolite isn't supported.
DATABASE_URL[database] urlIn 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_maxDefault 20 (v1: 10). Per replica.
POSTGRES_MIN_CONNECTIONS[database] pool_minDefault 2 (v1: 0). Applies to every backend.
POSTGRES_IDLE_TIMEOUT[database] idle_timeoutA 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_timeoutThe longest wait for a free pooled connection, a duration: 10000 is "10s". Default "5s" (v1: 10 s).
—[database] max_lifetimeNew. Replaces a connection after this long; default "30m". Every backend except SQLite.
LIBSQL_AUTH_TOKEN, LIBSQL_MAX_CONNECTIONSRemovedLibSQL isn't supported.
POSTGRES_TLS_CA, POSTGRES_TLS_CERT, POSTGRES_TLS_KEY (and POSTGRES_SSL_*)sslrootcert, sslcert, sslkey in [database] urlE.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_KEYssl-ca, ssl-cert, ssl-key in [database] urlE.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_UNAUTHORIZEDssl-mode in [database] url0 becomes ssl-mode=REQUIRED (TLS without verification); 1 becomes VERIFY_IDENTITY.
MSSQL_TLS_CAtrust_cert_ca in [database] urlSQL 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_UNAUTHORIZEDtrust_cert in [database] url0 becomes trust_cert=true (no verification). Can't be combined with trust_cert_ca.
MSSQL_TLS_CERT, MSSQL_TLS_KEYRemovedNo client certificates for SQL Server.
ORACLE_TLS_CAtcps connect string, plus a wallet for a private CAThe 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_UNAUTHORIZEDRemovedOracle Net verifies a tcps server certificate against the wallet, or the image's system CA bundle without one.
EXOTDB_DATABASE_ADDR, EXOTDB_ROOT_PASSWORDRemovedThe embedded database runs in-process and opens no port.
EXOTDB_DATABASE_LOCATION[database] urlurl = "sqlite:/path/to/sentinel.db". Default sqlite:<data_dir>/sentinel.db.
EXOTDB_ENCRYPTION_KEYRemovedThe 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_ADDRRemovedNo leader election over S3. Run several replicas on a shared database and Redis; see Clustering.

KV store (Redis)

v1 env varv2 TOML keyNotes
REDIS_URL[redis] nodesA 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_keyNew. 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] nodesSeveral entries are cluster seeds.
REDIS_KEY_PREFIX[redis] key_prefixDefault "sentinel:"; must be the same on every replica.
REDIS_COMMAND_TIMEOUT, REDIS_CONNECT_TIMEOUT[redis] timeoutOne duration for connecting and for each command, default "2s" (v1: 5000 and 10000 ms). Milliseconds become a duration: 5000 is "5s".
REDIS_MAX_RETRIESRemovedNo setting.
REDIS_SENTINEL_HOSTS[redis.sentinel] nodesURLs 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] masterRequired.
REDIS_SENTINEL_AUTHUserinfo of each [redis.sentinel] nodes URLredis://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, passwordCredentials for the master.
REDIS_SENTINEL_TLS, REDIS_SENTINEL_REDIS_TLSrediss:// in [redis.sentinel] nodesOne 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_URLRemovedThe 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 varv2 TOML keyNotes
SNAPSHOTS_ENABLED[snapshots] enabledDefault true.
SNAPSHOTS_MAIN_SCHEDULE[snapshots] scheduleCron, UTC. Needs [snapshots] identity and a [storage] provider. keep sets how many scheduled snapshots are kept (default 7).
SNAPSHOTS_REDIS_SCHEDULERemovedThe KV store isn't snapshotted.
SNAPSHOTS_KEY_PREFIX[snapshots] storage_prefixDefault "snapshots/".
SNAPSHOTS_AGE_SECRET_KEY[snapshots] identityAn age X25519 identity (AGE-SECRET-KEY-1…). When set, snapshots are encrypted to it and can be stored.
SNAPSHOTS_AGE_PUBLIC_KEY[snapshots] recipientsExtra recipients (age1…), e.g. an offline recovery key. Needs identity.
SNAPSHOTS_STORAGE_PROVIDER[storage] providers3 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_DIRRemovedNo 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 varv2 TOML keyNotes
STORAGE_PROVIDER[storage] providers3, azure, or none (default). local is removed.
STORAGE_LOCAL_DIRRemovedNo 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_idNo automatic AWS_ACCESS_KEY_ID fallback; write "${AWS_ACCESS_KEY_ID}".
STORAGE_S3_SECRET_ACCESS_KEY[storage.s3] secret_access_keyNo automatic fallback; write "${AWS_SECRET_ACCESS_KEY}".
STORAGE_S3_REGION[storage.s3] region
STORAGE_S3_ENDPOINT[storage.s3] endpointFor 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_ENABLEDRemoved/v1/blobs is gone. attachments[].contentUri is the object's native URI; fetch it with your storage credentials.

Caching

v1 env varv2 TOML keyNotes
CACHE_DURATION_API_KEYS[api_key_cache] refresh_intervalDefault "10s". Changes also reach every replica at once over pub/sub.
CACHE_DURATION_TRAINING_DATA[similarity] sync_intervalDefault "5m"; a fallback re-read, since changes apply over pub/sub.
CACHE_DURATION_USED_CHALLENGESRemovedA used payload is remembered in the KV store until it expires.

Logging

v1 env varv2 TOML keyNotes
LOG_LEVEL[log] levelA filter directive, e.g. "info" or "info,sentinel::http=debug". fatal and silent don't exist; use "error" or "off".
LOG_FORMAT[log] formatjson 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] retentionDefault "72h", at least "2h". Hourly stats are kept. With ClickHouse, use [clickhouse] raw_retention.
ACCESS_LOG_ENABLEDRemovedNo 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 varv2 TOML keyNotes
MONITORING_IP_WHITELIST[server] health_allowed_ips for /.health; [prometheus] allowed_ips for metricshealth_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_tokenFor metrics only: a Bearer token instead of Basic user:password. /.health has no credentials; restrict it with health_allowed_ips.

OpenTelemetry

v1 env varv2 TOML keyNotes
OTEL_EXPORTER_OTLP_ENDPOINT[telemetry] endpointSet [telemetry] enabled = true too. Without endpoint, the standard OTEL_EXPORTER_OTLP_* variables are read. Traces only.
OTEL_SERVICE_NAME[telemetry] service_nameDefault "altcha-sentinel".
OTEL_EXPORTER_OTLP_HEADERS[telemetry] headersA TOML table, e.g. { authorization = "Bearer ${OTEL_TOKEN}" }.
OTEL_EXPORTER_OTLP_TIMEOUT[telemetry] timeoutA 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 varv2 TOML keyNotes
CLICKHOUSE_URL[clickhouse] url, database, username, passwordSplit 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_intervalA duration; default "1s".
CLICKHOUSE_BATCH_MAX[request_logs] batch_sizeDefault 100.
CLICKHOUSE_TLS_CA[clickhouse] tls_caPEM 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_keyPEM 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 varv2 TOML keyNotes
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_keyPEM 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] keyNotes
Scheme, host, porturlldap:// or ldaps:// with host[:port] only.
namenameButton label.
userDnuser_dnA value containing USERNAME is a full bind-DN template.
usernameAttributeusername_attribute
usernameusername_template
adminDn, adminPasswordadmin_dn, admin_passwordSearch-then-bind. Use "${LDAP_ADMIN_PASSWORD}" for the password.
userSearchBaseuser_search_base
starttls=truestarttls = trueNow also applies the TLS options.
rejectUnauthorized=falsereject_unauthorized = falseNow also applies to StartTLS.
groupClass, groupMemberAttribute, groupMemberUserAttributegroup_class, group_member_attribute, group_member_user_attributeNow enforced, together with the new group_search_base and allowed_groups.
ALLOW_LDAPRemovedLDAP is on when [auth.ldap] is present.

Email

v1 env varv2 TOML keyNotes
SMTP_URLRemovedIt served Forms, which are removed. To email alerts, configure [alerts.email] (host, port, tls, username, password, from, to).
EML_BODY_LIMIT[eml] max_body_sizeIn bytes; default 5000000.

AI providers

v1 env varv2 TOML keyNotes
AI_PROVIDER, AI_PROVIDER_MODEL, AI_PROVIDER_OPTIONS, AI_PROVIDER_REQUEST_OPTIONSRemovedAI 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_KEYRemovedv2 has no context override.

Threat intelligence

v1 env varv2 TOML keyNotes
THREATS_ENABLEDRemovedThreat 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] storefile (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_LIMITRemovedOnly 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 varv2 TOML keyNotes
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", keyWithout 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", urlPass the API token in token, not in the URL.
IPINFO_IO_MMDB_DOWNLOAD_SCHEDULE, IPINFO_IO_MMDB_DOWNLOAD_HEADERSschedule, headers of that provider
MAXMIND_ACCOUNT_ID, MAXMIND_LICENSE_KEY[[ip_resolver.providers]] type = "maxmind", account_id, license_key
MAXMIND_DOWNLOAD_URLurl of the maxmind providerNo default: set the download URL, or a local path to an .mmdb file.
MAXMIND_DOWNLOAD_SCHEDULE, MAXMIND_DOWNLOAD_HEADERSschedule, headers of the maxmind provider
HIGH_RISK_COUNTRIESSecurity-group setting classifier.highRiskCountriesPer security group, not server-wide. The default list high_risk has the same 19 countries as v1. See Rules reference.
HIGH_RISK_COUNTRIES_EXCLUDERemovedList the countries you want in classifier.highRiskCountries.
PENALTY_TTL[penalty] ttlDefault "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 varv2 TOML keyNotes
PHISHING_LIST_URL[classifier.phishing] urlDefault is the ALTCHA directory's phishing.csv.gz. A PhishTank CSV still works.
PHISHING_LIST_SCHEDULE[classifier.phishing] scheduleDefault "@daily".
EMAIL_LIST_DISPOSABLE[classifier.disposable] url
EMAIL_LIST_DISPOSABLE_SCHEDULE[classifier.disposable] schedule
USER_AGENT_LIST_URL[classifier.user_agents] urlA 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_LIMITmax_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_ENTRIESmax_entries of the same tablesDefaults: 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 varv2 TOML keyNotes
FLOOD_RATE_LIMIT[rate_limit] globalDefault "100/1m". Disable with [rate_limit] enabled = false, not an empty value.
FLOOD_RATE_LIMIT_KEYRemovedThe 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_limitDefault "10/5m", per client IP. "" means unlimited.
AUDIO_CHALLENGE_DELAY[code_challenge] audio_delayDefault "3s".
POW_MAX_MEMORY[pow] max_memory_costIn KiB: 128MB is 131072. Default 262144 (256 MiB).
POW_MAX_THREADS[pow] cpusDefault: half the available CPUs.

Spam handling

v1 env varv2 TOML keyNotes
DELETE_SPAM_SUBMISSIONS_INRemovedForm submissions are removed with Forms.

Container resource limits

v1 env varv2 TOML keyNotes
CONTAINER_CPUSRemovedSet [pow] cpus to cap proof-of-work derivations.
CONTAINER_MEMORY_LIMIT_MBRemovedThe memory alert reads the cgroup limit itself.
HEAP_LIMIT_MBRemovedv2 isn't a Node.js process; there is no heap to size.

Start typing to search...

↑ ↓ Navigate ↵ Select