Skip to main content
ALTCHA®

Configuration reference

Every section and key of sentinel.toml, in the order of the example configuration file.

Sentinel reads the file given with --config / -c, otherwise sentinel.toml in the working directory when present. Every key is optional. Unknown keys and invalid values stop startup, and changes take effect only after a restart. For loading, layout, and examples, see The configuration file.

Value expansion. Any string value may embed references that are expanded at startup:

SyntaxResult
"${VAR}"Value of environment variable VAR; empty string when unset or empty.
"${VAR:-fallback}"Value of VAR, or fallback when unset or empty.
"${file:/path}"Contents of the file at /path, one trailing newline trimmed (e.g. a Docker or Kubernetes secret mount). A missing file without a fallback stops startup.
'\${VAR}'The literal text ${VAR} (escaped, not expanded). Expansion runs after TOML parsing, so the backslash must reach Sentinel: use a single-quoted literal string, or "\\${VAR}" in a double-quoted one.

A string that is empty, literally or after expansion, counts as unset. Numbers and booleans are literal and never expanded. See Secrets.

Formats. duration values are strings with a unit, such as "500ms", "30s", "5m", "24h", or "90d". Rate strings use N/duration, for example "100/1m". Schedules are cron expressions (UTC) or shortcuts like @hourly, @daily, @weekly, @monthly. Ranges given in descriptions are enforced at startup.

Sections

SectionPurpose
Top levelData directory.
[server]Main API listener.
[server.public_api]Widget-only listener.
[server.admin_ui]Web app listener.
[log]Log level and format.
[database]Main database.
[redis]KV store for rate limits, penalties, and pub/sub.
[redis.sentinel]Redis master discovery through Redis Sentinel.
[secrets]Signing and encryption keys.
[license]License file or key.
[auth]Sign-in, sessions, OAuth, LDAP.
[rate_limit]Global per-IP rate limit.
[edk]Daily device key.
[inspect]GET /v2/inspect.
[penalty]Per-client penalties.
[bootstrap]First-boot root password.
[privacy]IP anonymization.
[request_logs]Request log retention and buffering.
[audit_logs]Audit log recording and retention.
[alerts]Alerts, deliveries, and alert rules.
[clickhouse]ClickHouse request log store.
[ip_resolver]IP geolocation providers.
[api_key_cache]In-memory API key cache.
[threats]Threat intelligence.
[classifier]Classifier lists, DNS, and AI decider.
[eml]Email (EML) analysis.
[storage]Object storage.
[snapshots]Database snapshots.
[web_bot_auth]Web Bot Auth agent keys.
[pow]Proof-of-work limits.
[prometheus]Metrics endpoint.
[telemetry]OpenTelemetry tracing.
[assistant]Web app AI assistant.
[releases]Release feed.
[code_challenge]Code challenge images and audio.
[similarity]Similarity matching and campaigns.

Top level

Keys outside any table.

KeyTypeDefaultDescription
tls_extra_ca_certsstring—PEM CA certificate(s) trusted next to the system CA store by every outbound TLS connection: HTTP clients (webhooks, OAuth, remote files, AI APIs, object storage, ClickHouse, the license server), OTLP, SMTP, LDAP, the database, Redis, and an ExotDB server. Usually "${file:/etc/sentinel/extra-ca.pem}". A CA that replaces the system store for one connection ([auth.ldap] tls_ca, sslrootcert or ssl-ca in [database] url) replaces these too. Not used by Oracle. Invalid PEM stops startup.
data_dirstring"./data"Directory for the embedded SQLite database, generated secrets, downloaded remote files, threat indexes, and other local state.

See Storage and data directory.

[server]

The main API listener, serving every /v2 route, the GET / liveness probe, and the GET /.health storage status.

KeyTypeDefaultDescription
hoststring (IP)"0.0.0.0"Address to listen on.
portinteger3000Port to listen on.
trusted_proxiesstring[][]CIDRs or IPs of reverse proxies whose X-Forwarded-For / X-Real-IP are trusted on this listener. Empty: the TCP peer is the client.
client_ip_headerstring—Header set by a CDN holding the client IP (e.g. CF-Connecting-IP, Fastly-Client-IP, True-Client-IP). Checked first; accepted from any peer when trusted_proxies is empty, so only expose the server through the CDN.
forwarded_host_headerstring—Header holding the original host when a proxy rewrites Host (e.g. X-Forwarded-Host). Web Bot Auth verifies against it. Trusted like client_ip_header.
base_urlstring—Public URL of this listener (e.g. https://example.com/sentinel). Its path prefixes URLs handed to widgets (verifyUrl, HIS url, code challenge audio). Also the OAuth and passkey URL unless [auth] base_url or an enabled [server.admin_ui] base_url is set.
allowed_hostsstring[][]Hosts this listener answers /v2 for; others get 421. See Allowed hosts. Empty: any host.
health_allowed_ipsstring[]private networksCIDRs or IPs of clients allowed GET /.health, resolved per trusted_proxies / client_ip_header. Default: 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, 169.254.0.0/16, ::1/128, fc00::/7, fe80::/10. []: any client.
v1_compatbooleanfalseServe /v1/challenge, /v1/challenge/audio/<file>, /v1/verify, and /v1/verify/signature as aliases of the /v2 routes on every [server.*] listener (ALTCHA widget v3+, PoW v2 only). Rules still see /v2 paths.
tlstable—Serve this listener over HTTPS: { cert = "…", key = "…" }. See Listener TLS. Unset: plain HTTP.
idle_timeoutduration"620s"Every listener: a connection with no request in flight this long is closed (1s–24h). See Connection timeouts.
header_read_timeoutduration"30s"Every listener: longest wait for a complete request head (1s–10m).
body_read_timeoutduration"30s"Every listener: longest wait for the next part of a request body (1s–10m).
write_timeoutduration"30s"Every listener: longest a response may wait on the client (1s–10m).

See Listeners & reverse proxy.

Allowed hosts

allowed_hosts on [server], [server.public_api], [server.admin_ui] or [prometheus] lists the hosts that listener answers for. Each listener has its own list; nothing is inherited from [server]. Empty (the default) answers any host. A request addressed to another host gets 421 Misdirected Request with a plain-text body. This stops a page whose own domain resolves to Sentinel (DNS rebinding) from calling the API through a visitor's browser.

[server]
allowed_hosts = ["sentinel.example.com", "*.sentinel.example.com", "10.0.0.5"]
  • Entries are a host name, an IP (IPv6 bare or in brackets), or *.domain, which matches any subdomain of domain but not domain itself. No scheme, port, or path; an invalid entry stops startup. Names match case-insensitively and a trailing dot is ignored. The port is never compared.
  • The host comes from the listener's forwarded_host_header when set and sent by a trusted peer, else Host, else the HTTP/2 :authority. [prometheus] has no forwarded host header. A request without a host gets 421 too. With forwarded_host_header and empty trusted_proxies, any client can set the forwarded host, a rebinding page included, so list your proxies.
  • Checked paths. On [server] and [server.public_api], only /v2 (and the /v1 aliases) is checked. GET /, GET /.health, and the honeypot paths answer any host, so load balancer probes and healthcheck, which address the IP, keep working. [server.admin_ui] checks its static files too, and [prometheus] its metrics path.
  • Prometheus usually scrapes <ip>:<port>, so list that IP in [prometheus] allowed_hosts.

Health endpoint

GET /.health on the main listener reports whether this replica reaches its storage, for uptime monitors and dashboards. [server.public_api] and [server.admin_ui] don't serve it.

{"status": "healthy", "checks": {"kv": {"ok": true}, "db": {"ok": true}, "clickhouse": {"ok": true}}}
  • Status. 200 with "status": "healthy" when every check is ok; 503 with "unhealthy" otherwise.
  • Checks. kv is the KV store (Redis or the built-in KV), db the database, and clickhouse is present only with a licensed [clickhouse]. The endpoint answers from background probes (every 10 s, 5 s timeout) and never queries storage itself. A check whose last probe is older than 30 s fails.
  • No details. Errors, latencies, and the version aren't included; root users see them in storage of GET /v2/cluster/replicas.
  • Like GET /, it answers any host, needs no license, and isn't rate limited or written to request logs. It counts toward the replica's requests.
  • Access is by client IP, [server] health_allowed_ips, private networks by default. The client IP is resolved as for the rest of the listener; an IPv4-mapped IPv6 address matches its IPv4 range. Other clients get 403 IP_NOT_ALLOWED. So does a request with X-Forwarded-For, X-Real-IP, Forwarded, or the client_ip_header from a peer outside trusted_proxies, which would otherwise make every client look like the proxy's private IP.
  • Public probers need adding: Google Cloud load balancers (35.191.0.0/16, 130.211.0.0/22), Azure (168.63.129.16), and external uptime monitors. Probes from Docker, Kubernetes, or AWS ALB/NLB connect from private addresses and need no setting.
[server]
health_allowed_ips = ["10.0.0.0/8", "35.191.0.0/16", "130.211.0.0/22"]

Listener TLS

tls on [server], [server.public_api], [server.admin_ui] or [prometheus] serves that listener over HTTPS (TLS 1.2 and 1.3), with HTTP/2 and HTTP/1.1 negotiated by ALPN. Each listener has its own setting; nothing is inherited. Without tls, a listener serves plain HTTP/1.1, and HTTP/2 to clients that open with the HTTP/2 preface (prior knowledge).

KeyTypeDefaultDescription
certstring— (required)PEM certificate chain, leaf certificate first.
keystring— (required)PEM private key matching cert (PKCS#8, PKCS#1 or SEC1).
[server]
tls = { cert = "/etc/sentinel/tls/fullchain.pem", key = "/etc/sentinel/tls/privkey.pem" }
  • Paths are file paths, relative to the working directory (/home/nonroot in the image), not to sentinel.toml.
  • Loaded at startup. A missing file, invalid PEM, or a key that doesn't match the certificate stops startup (for example server.tls.cert: reading … or server.tls: certificate and key). doctor --config-only runs the same check and reports it as FAIL config.valid (server.tls). A listener that isn't enabled doesn't read its files, and neither does doctor.
  • Renewal needs a restart. Sentinel doesn't reload a renewed certificate. Restart the process after a renewal, or terminate TLS at a proxy instead.
  • No client certificates. Mutual TLS isn't supported.
  • A client gets 10 seconds to complete its TLS handshake.

With [server] tls set, altcha-sentinel healthcheck probes over HTTPS without checking the certificate.

Connection timeouts

The four timeouts are set in [server] and apply to every listener, including [server.public_api], [server.admin_ui] and [prometheus].

KeyStartsWhen it expires
idle_timeoutWhen the connection has no request in flightThe connection closes gracefully. Keep it above the keep-alive timeout of any load balancer or proxy in front (AWS ALB 60s, nginx 60s, Google Cloud 600s); otherwise the proxy may reuse a connection as Sentinel closes it, and return a 502.
header_read_timeoutOn a new connection, or at the first byte of the next request on an idle HTTP/1.1 connectionThe connection is dropped. HTTP/2 request heads are bounded by idle_timeout instead.
body_read_timeoutAt each read of the request body that waits for dataThe request fails with 400 VALIDATION_ERROR (request body read timed out). The HTTP/1.1 connection then closes; on HTTP/2 only the stream ends.
write_timeoutWhen a response waits on the client: a blocked write, or HTTP/2 flow control holding the next partThe connection is dropped.

body_read_timeout and write_timeout count the wait between parts, not the whole transfer, so a slow but steady upload or download isn't cut off.

[server.public_api]

An optional listener for the widget endpoints only: /v2/challenge, /v2/challenge/audio/<file>, /v2/verify, and /v2/inspect (with [inspect]). Every other /v2 path returns 404. GET / and the honeypot paths are served; GET /.health isn't. Nothing is inherited from [server] except its connection timeouts.

KeyTypeDefaultDescription
enabledbooleanfalseStart this listener.
hoststring (IP)"0.0.0.0"Address to listen on.
portinteger3003Port to listen on.
trusted_proxiesstring[][]As in [server], for this listener only.
client_ip_headerstring—As in [server], for this listener only.
forwarded_host_headerstring—As in [server], for this listener only.
allowed_hostsstring[][]As in [server], for this listener only; see Allowed hosts.
base_urlstring—Public URL of this listener; its path prefixes the widget URLs answered here.
verify_signaturebooleanfalseAlso serve POST /v2/verify/signature.
tlstable—Serve this listener over HTTPS; see Listener TLS.

See Listeners & reverse proxy.

[server.admin_ui]

The web app on its own listener: its static files (with index.html for unknown paths) plus /v2 exactly as on [server]. Nothing is inherited from [server] except its connection timeouts.

KeyTypeDefaultDescription
enabledbooleanfalseStart this listener.
hoststring (IP)"127.0.0.1"Address to listen on.
portinteger3002Port to listen on.
dirstring—Directory of a web app build. Unset: the copy embedded in the binary (as in the release image); a binary without one refuses to start.
allowed_ipsstring[][]CIDRs or IPs of allowed clients, resolved per this listener's trusted_proxies / client_ip_header. Empty: any. Applies to /v2 on this port too.
api_referencebooleantrueServe the public API reference page, rendering GET /v2/openapi.json.
trusted_proxiesstring[][]As in [server], for this listener only.
client_ip_headerstring—As in [server], for this listener only.
forwarded_host_headerstring—As in [server], for this listener only.
allowed_hostsstring[][]As in [server], for this listener only, and checked for its static files too; see Allowed hosts.
base_urlstring—Public URL of the app. Prefixes the widget URLs answered here, and is the OAuth and passkey URL unless [auth] base_url is set. Include any path prefix (e.g. https://example.com/admin).
tlstable—Serve the app over HTTPS; see Listener TLS.

The session cookie is always Secure; browsers accept it over plain HTTP only on localhost, so serve the app over HTTPS: set tls, or put a TLS proxy in front. See Listeners & reverse proxy.

[log]

Log output on stdout: filtering and line format.

KeyTypeDefaultDescription
levelstring"info"Log filter directive. "info,sentinel::http=debug" logs every 4xx/5xx response; "info,sentinel::http=trace" every response. MSSQL driver logs are warn and above unless re-enabled (e.g. "info,tiberius=info").
formatstring"text"text: human-readable lines. json: one JSON object per line with timestamp, level, and target, the event's fields (including message) at the top level, and the enclosing span and spans when the event is inside one. Use json for log collectors.

See Troubleshooting.

[database]

The main database.

KeyTypeDefaultDescription
urlstringsqlite:<data_dir>/sentinel.dbConnection URL. Schemes: sqlite: (bundled SQLite 3.54.1), postgres:// / postgresql:// (PostgreSQL 16 or later), mysql:// (MySQL 8.0.13 or later), mariadb:// (MariaDB 11.4 LTS or later, checked at startup), mssql:// / sqlserver:// (SQL Server 2022 or later), oracle:// (Oracle 21c or later; needs the -oracle image, which ships the Oracle Instant Client), or http(s):// for an ExotDB server. mysql:// refuses a MariaDB server and mariadb:// a MySQL server. May contain secrets via expansion, e.g. "postgres://app:${DB_PASSWORD}@db:5432/sentinel". SQL TLS options are query parameters; see Database TLS.
tokenstring—Access token; ExotDB server only.
namestring"sentinel"Database name; ExotDB server only.
table_prefixstring""Prepended to every table, index, and relation name and to database lock names, e.g. "sentinel_" to share a database. Up to 24 characters of a-z, 0-9, _, starting with a letter. Changing it starts on new, empty tables.
sqlite_journal_modestring"wal"Embedded SQLite database file only: wal or delete, the journal mode the database and the built-in KV store set at startup. wal lets reads run alongside writes but needs shared memory, which breaks on network storage (AWS EFS, NFS, SMB); use delete there. Switching an existing file needs every other process to close it first. Ignored by other databases. See SQLite on network storage.
tls_castring—PEM CA certificate(s) of an https:// ExotDB server, trusted next to the system CA store.
tls_certstring—PEM client certificate chain, leaf first, for an https:// ExotDB server. Set together with tls_key.
tls_keystring—PEM private key of tls_cert: PKCS#1, PKCS#8, or SEC1.
pool_mininteger2Connections the pool keeps open. At most pool_max.
pool_maxinteger20Most connections the pool opens, at least 1. An in-memory SQLite database always uses one. Each replica has its own pool, so the database sees up to pool_max × replicas connections.
acquire_timeoutduration"5s"Longest wait for a free connection; then the database call fails. "0s" waits forever.
max_lifetimeduration"30m"A connection is replaced after this long. "0s": never. Not SQLite.
idle_timeoutduration"10m"A connection idle this long is closed. "0s": never. Not SQLite.
request_timeoutduration"60s"ExotDB server only: longest wait for one HTTP request. At most 1h. With auto_migrate, above 30s (the migration-lock wait, so a starting replica doesn't time out while another migrates).
auto_migratebooleantrueCreate and upgrade the tables at startup (on an embedded database, ExotDB's system tables and the built-in KV store's too). false: no schema changes; startup fails unless the schema is current, and altcha-sentinel schema sql prints the migration for a database administrator. See Schema migrations.

The tls_* keys apply only to an https:// ExotDB server; with any other url they stop startup. The pool keys apply to every SQL backend (sqlite:, postgres://, mysql://, mariadb://, mssql://, oracle://); an ExotDB server sizes its own pool. Pool durations are "0s" (no limit) or at least 1ms.

License: database backends other than SQLite need the matching exotdb.backend.<kind> feature (e.g. exotdb.backend.postgres). See Databases.

Database TLS

PostgreSQL, MySQL, MariaDB, and SQL Server take TLS options as query parameters of url. Certificate options take file paths. The system CA store, the AWS RDS CA bundle, and tls_extra_ca_certs are trusted unless the URL names its own CA.

BackendParametersDefault
PostgreSQLsslmode (disable, allow, prefer, require, verify-ca, verify-full), sslrootcert, sslcert, sslkeyprefer: TLS when the server offers it, without certificate verification
MySQL, MariaDBssl-mode (DISABLED, PREFERRED, REQUIRED, VERIFY_CA, VERIFY_IDENTITY), ssl-ca, ssl-cert, ssl-keyPREFERRED: TLS when the server offers it, without certificate verification
SQL Servertrust_cert_ca (a CA file), trust_cert=true (skip verification; not with trust_cert_ca), encrypt=false (no TLS)Encrypted and verified
OracleIn the connect string, tnsnames.ora, or sqlnet.ora; see Oracle TLSPlain TCP unless the connect string uses tcps
[database]
url = "postgres://sentinel:${DB_PASSWORD}@db.internal:5432/sentinel?sslmode=verify-full&sslrootcert=/run/secrets/db-ca.pem"

Oracle TLS

Oracle connections go through the Oracle Instant Client in the -oracle image (version 23.26, at /opt/oracle/instantclient). Sentinel splits oracle://user:password@<connect string> at the first : and the last @, and passes the connect string to Instant Client unchanged. User and password aren't percent-decoded. TLS is therefore configured the Oracle way, and tls_extra_ca_certs doesn't apply.

Server certificate from a public CA. Use tcps in an Easy Connect string. Instant Client verifies the server against the image's system CA bundle, so no wallet is needed:

[database]
url = "oracle://sentinel:${ORACLE_PASSWORD}@tcps://db.example.com:2484/FREEPDB1?ssl_server_dn_match=true"

ssl_server_dn_match=true checks that the certificate matches the host; use the host name in the certificate's CN or SAN.

Private or self-signed CA, or client certificates (mTLS). Instant Client needs an auto-login wallet, cwallet.sso; it doesn't read ewallet.pem. The image has no orapki, so build the wallet with an Oracle database image, here for a CA certificate ca.pem:

mkdir wallet && cp ca.pem wallet/
docker run --rm --user root -v "$PWD/wallet:/w" container-registry.oracle.com/database/free:latest bash -c '
  orapki wallet create -wallet /w -auto_login_only &&
  orapki wallet add -wallet /w -trusted_cert -cert /w/ca.pem -auto_login_only &&
  chmod 644 /w/cwallet.sso'

For mTLS, the wallet also holds the client key and certificate. Export them as PKCS#12 (openssl pkcs12 -export -inkey client.key -in client.pem -out wallet/client.p12), then run these commands in the same container instead: the wallet gets a password and -auto_login, which keeps cwallet.sso next to the password-protected ewallet.p12.

orapki wallet create -wallet /w -pwd "$WALLET_PASSWORD" -auto_login &&
orapki wallet add -wallet /w -pwd "$WALLET_PASSWORD" -trusted_cert -cert /w/ca.pem &&
orapki wallet import_pkcs12 -wallet /w -pwd "$WALLET_PASSWORD" -pkcs12file /w/client.p12 -pkcs12pwd "$P12_PASSWORD" &&
chmod 644 /w/cwallet.sso

Mount the wallet read-only and point wallet_location at it. Sentinel runs as uid 65532, so cwallet.sso must be readable by that user:

services:
  sentinel:
    image: ghcr.io/altcha-org/sentinel:2.0.0-beta.1-oracle
    environment:
      ORACLE_PASSWORD: ${ORACLE_PASSWORD}
    volumes:
      - ./sentinel.toml:/home/nonroot/sentinel.toml:ro
      - ./wallet:/etc/sentinel/oracle-wallet:ro
[database]
url = "oracle://sentinel:${ORACLE_PASSWORD}@tcps://db.example.com:2484/FREEPDB1?wallet_location=/etc/sentinel/oracle-wallet&ssl_server_dn_match=true"

Net service name. To keep the URL short, put cwallet.sso and a tnsnames.ora in one directory. Mount it at /opt/oracle/instantclient/network/admin, Instant Client's default TNS_ADMIN, or anywhere with the TNS_ADMIN environment variable set to it. The URL then names the entry: oracle://sentinel:${ORACLE_PASSWORD}@SENTINEL_DB.

SENTINEL_DB =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCPS)(HOST = db.example.com)(PORT = 2484))
    (CONNECT_DATA = (SERVICE_NAME = FREEPDB1))
    (SECURITY =
      (SSL_SERVER_DN_MATCH = TRUE)
      (WALLET_LOCATION = /opt/oracle/instantclient/network/admin)))

[redis]

The KV store for rate-limit counters, penalties, replay protection, and pub/sub.

KeyTypeDefaultDescription
nodesstring[][]Redis URLs, e.g. ["redis://127.0.0.1:6379"]. One entry is a standalone server; several are Redis Cluster seed nodes. rediss:// connects over TLS and verifies the server against the system CA store, tls_extra_ca_certs, and tls_ca; append #insecure (rediss://host:6380/#insecure) to skip verification. Empty: built-in KV on the Sentinel database (single node only), or the master found through [redis.sentinel]. Required for multi-node deployments and with an ExotDB server, unless [redis.sentinel] is set.
builtinstring"database"Where the built-in KV store (empty nodes) keeps its keys: database (a table in the Sentinel database) or memory (lost on restart, together with replay protection and rate-limit state). Not with an ExotDB server database.
synchronousstring"full"Built-in KV store on an SQLite database file only: full syncs every commit to disk; normal skips the per-commit sync (faster writes, survives restarts) but a power loss or OS crash can drop the last writes, so a replay-protection key could be accepted again. Ignored with nodes, builtin = "memory", and other database backends.
key_prefixstring"sentinel:"Prepended to every key and pub/sub channel (built-in KV too). 1–64 printable ASCII characters without spaces, {, or }. Must match on every replica. Changing it starts with empty counters, penalties, and replay claims.
timeoutduration"2s"Connect and response timeout of every KV command, built-in KV included; also bounds each Redis Sentinel lookup and pub/sub subscribe. A timed-out command counts as a KV failure toward redis_fail_threshold. 1ms to 60s, whole milliseconds.
tls_castring—PEM CA certificate(s) of rediss:// nodes, trusted next to the system CA store.
tls_certstring—PEM client certificate chain, leaf first, for rediss:// nodes. Set together with tls_key.
tls_keystring—PEM private key of tls_cert: PKCS#1, PKCS#8, or SEC1.

The tls_* keys need every node to be rediss:// (with [redis.sentinel], every Sentinel address); otherwise they stop startup.

See Clustering.

[redis.sentinel]

Finds the Redis master through Redis Sentinel and follows failovers. [redis] nodes must be empty. Doesn't work with an ExotDB server's KV port, which isn't a Redis Sentinel.

KeyTypeDefaultDescription
nodesstring[]—Required, at least one. Redis Sentinel addresses, e.g. ["redis://:${REDIS_SENTINEL_PASSWORD}@s1:26379", "redis://:${REDIS_SENTINEL_PASSWORD}@s2:26379"]. All redis:// or all rediss://, and all or none with #insecure. The userinfo authenticates to the Sentinels and must be the same on every entry. rediss:// also connects to the master over TLS, with the [redis] tls_* keys and #insecure applying to both.
masterstring—Required. The master name the Sentinels monitor (sentinel monitor <name> …).
usernamestring—ACL user for the master. Unset: the default user.
passwordstring—Password for the master. Unset: no AUTH.

Every new connection, including pub/sub reconnects, asks the Sentinels in turn for the current master, skips masters they flag as down, and checks ROLE on the one reported. Each Sentinel gets [redis] timeout (default 2s), so a dead Sentinel only delays discovery. After a failover, the demoted master rejects writes with READONLY; Sentinel then drops the connection and the next command reconnects to the new master. Commands in between count as KV failures; see redis_fail_threshold.

[redis.sentinel]
nodes    = ["redis://:${REDIS_SENTINEL_PASSWORD}@s1:26379", "redis://:${REDIS_SENTINEL_PASSWORD}@s2:26379", "redis://:${REDIS_SENTINEL_PASSWORD}@s3:26379"]
master   = "mymaster"
password = "${REDIS_PASSWORD}"

[secrets]

Signing and encryption keys. When unset, they are generated into <data_dir>/secrets.json (embedded SQLite only); multi-node and external databases need them set explicitly.

KeyTypeDefaultDescription
jwt_secretstringgeneratedSession token signing secret; at least 24 characters.
altcha_hmac_secretstringgeneratedSigning secret of the admin sign-in challenge; at least 24 characters. Widget challenges are signed with the API key's secret.
encryption_keystringgeneratedEncrypts stored API key and TOTP secrets and the OAuth state cookie, and derives the EDK; 64 hex characters.
vapid_private_keystringgenerated when [alerts.push] is on (embedded SQLite only)Web push key for [alerts.push]: base64url P-256 private key (e.g. from npx web-push generate-vapid-keys). Required with other databases when web push is on.
[secrets]
jwt_secret         = "${file:/run/secrets/jwt_secret}"
altcha_hmac_secret = "${file:/run/secrets/altcha_hmac_secret}"
encryption_key     = "${file:/run/secrets/encryption_key}"

See Secrets.

[license]

How the license is installed. Set at most one of file and key.

KeyTypeDefaultDescription
filestring—Path of a signed license file, verified offline; imported at startup when newer than the stored license.
keystring—Online activation key (SENT-…); enables activation and daily refresh. Never stored. Not with file.
serverstring"https://license.altcha.org"License server for activation and refresh. Only the URL can be changed; it cannot be turned off.
standbybooleanfalseStart as a standby instance: take no instance slot, answer only GET / (503 LICENSE_STANDBY otherwise), and start fully once a regular slot has been free for 15 seconds. Never takes a burst slot.

Without an active license, challenges, verification, and feature endpoints are not served. Without a usable license, Sentinel also runs on SQLite only with 3 instances, 1 account, 1 user, 1 API key, and 1 security group. See Licensing.

[auth]

Sign-in and session settings for the web app and management API.

KeyTypeDefaultDescription
jwt_issuerstring"ALTCHA_SENTINEL"Issuer claim of session tokens.
jwt_ttlduration"24h"Session token lifetime.
verify_altchabooleantrueRequire the ALTCHA check on login. false is for testing only.
password_loginbooleantruefalse disables POST /v2/auth/login for every user; requires [auth.oauth.*] or [auth.ldap].
block_threatsbooleantrueRefuse the login steps (password, LDAP, second factor, OAuth) with 403 IP_BLOCKED from client IPs whose threat entries (manual or auto, not source lists) decide block. See Blocking logins.
base_urlstring—Public URL for OAuth and passkeys; overrides [server.admin_ui] base_url and [server] base_url. OAuth redirect URI: <base_url>/v2/auth/oauth/<provider>/callback. With a domain host it also enables passkeys (the WebAuthn RP ID is the host).
oauthtable—OAuth providers; see the [auth.oauth.*] sections below.
ldaptable—LDAP login; see [auth.ldap].

See Sign-in.

[auth.oauth.azure]

Microsoft Entra ID (single tenant) sign-in. A provider is enabled when its table is present; first login creates the user <provider>:<id> as a member of the default accounts.

KeyTypeDefaultDescription
namestringprovider nameButton label.
client_idstring— (required)OAuth client ID.
client_secretstring— (required)OAuth client secret, e.g. "${AZURE_CLIENT_SECRET}".
tenant_idstring— (required)Directory (tenant) ID GUID; not common or organizations.

License: needs the oauth feature. See Sign-in.

[auth.oauth.google]

Google Workspace sign-in (one hosted domain).

KeyTypeDefaultDescription
namestringprovider nameButton label.
client_idstring— (required)OAuth client ID.
client_secretstring— (required)OAuth client secret, e.g. "${GOOGLE_CLIENT_SECRET}".
hosted_domainstring— (required)Required hd claim, e.g. "example.com".

License: needs the oauth feature. See Sign-in.

[auth.oauth.keycloak]

Keycloak (OpenID Connect) sign-in.

KeyTypeDefaultDescription
namestringprovider nameButton label.
client_idstring— (required)OAuth client ID.
client_secretstring— (required)OAuth client secret, e.g. "${KEYCLOAK_CLIENT_SECRET}".
issuerstring— (required)Issuer URL, e.g. https://id.example.com/realms/corp.

License: needs the oauth feature. See Sign-in.

[auth.oauth.okta]

Okta (OpenID Connect) sign-in.

KeyTypeDefaultDescription
namestringprovider nameButton label.
client_idstring— (required)OAuth client ID.
client_secretstring— (required)OAuth client secret, e.g. "${OKTA_CLIENT_SECRET}".
issuerstring— (required)Issuer URL, e.g. https://corp.okta.com/oauth2/default.

License: needs the oauth feature. See Sign-in.

[auth.ldap]

LDAP sign-in (POST /v2/auth/ldap); enabled when the table is present. First login creates the user ldap:<lowercased username> as a member of the default accounts. Use either direct bind (user_dn) or search-then-bind (admin_dn + user_search_base).

KeyTypeDefaultDescription
namestring"LDAP"Button label.
urlstring— (required)ldap:// or ldaps:// URL, host and optional port only.
user_dnstring—Direct bind: a bind-DN template containing USERNAME, or a base so the DN becomes <username_attribute>=<value>,<user_dn>.
username_attributestring"uid"Attribute naming the user in the DN and search filter.
username_templatestring—Value used in the DN and search filter, e.g. "USERNAME@corp.example". Unset: the username as typed.
admin_dnstring—Search-then-bind: service account DN.
admin_passwordstring—Service account password, e.g. "${LDAP_ADMIN_PASSWORD}".
user_search_basestring—Base DN of the user search; also read for the display name (cn) after a direct bind.
starttlsbooleanfalseUse StartTLS on ldap://.
reject_unauthorizedbooleantruefalse skips server certificate verification.
tls_castring—PEM CA bundle replacing the system roots and tls_extra_ca_certs, e.g. "${file:/etc/sentinel/ldap-ca.pem}". Unset: the system roots plus tls_extra_ca_certs.
tls_certstring—PEM client certificate chain, leaf first.
tls_keystring—PEM client key (PKCS#1, PKCS#8, or SEC1).
group_search_basestring—Base DN of the group search; set together with allowed_groups.
group_classstring"groupOfNames"Object class of groups (posixGroup for memberUid groups).
group_member_attributestring"member"Group attribute listing members (memberUid for posixGroup).
group_member_user_attributestring"dn"User value stored in the member attribute: dn, or a user attribute such as uid.
allowed_groupsstring[][]Groups allowed to sign in: a cn, or a group DN (contains =). Empty: no group restriction.

License: needs the ldap feature. See Sign-in.

[rate_limit]

The global rate limit per client IP on every /v2 request, stored in the KV store.

KeyTypeDefaultDescription
enabledbooleantrueThe only way to disable the global limit.
globalstring"100/1m"Comma-separated points/duration[(params)] limits, e.g. "100/1m,1000/1h(sliding)".
memory_fallbackbooleantrueLimit in memory while the KV store is down. false: fail open.
memory_max_keysinteger100000Maximum keys of the in-memory fallback.
redis_fail_thresholdinteger3Consecutive KV failures, including commands that time out after [redis] timeout, before switching to the fallback.

See Rate limiting.

[edk]

The daily device key (EDK): the default key of security-group rate limits and part of GET /v2/inspect.

KeyTypeDefaultDescription
seed_headerstring—Header with a per-user seed set by your proxy (e.g. a user ID); trusted like client_ip_header.
seed_cookiestring—Name of a signed seed cookie: <seed>.<hex HMAC-SHA256(seed_cookie_secret, seed)>. Same-site deployments only.
seed_cookie_secretstring—Cookie signing secret, at least 24 characters; required with seed_cookie. Use "${EDK_SEED_COOKIE_SECRET}".
time_zonestring"UTC"IANA time zone whose midnight rotates EDKs; pick one where midnight is low traffic.

See Rate limiting.

[inspect]

The GET /v2/inspect endpoint.

KeyTypeDefaultDescription
enabledbooleantrueServe GET /v2/inspect.
security_rulesbooleanfalseInclude securityRules (how each security-group rule evaluated). Debugging only: public callers would see which conditions they trip.

See Backend APIs.

[penalty]

Per-client penalties (account + client IP) in the KV store, used by the penalty rule condition and GET /v2/inspect.

KeyTypeDefaultDescription
ttlduration"30m"A penalty expires this long after its last increase; at least 1s.

See Security rules.

[bootstrap]

First-boot setup.

KeyTypeDefaultDescription
root_passwordstringrandom (logged)Password of the root user, applied on first boot only, e.g. "${ROOT_PASSWORD}".

See Get started.

[privacy]

Client IP handling in stored data and logs.

KeyTypeDefaultDescription
anonymize_ipbooleanfalseZero the last IPv4 octet / IPv6 segment of public client IPs (203.0.113.77 → 203.0.113.0) in request logs, audit logs, alerts (see [alerts] anonymize_ip), and log lines. Threat entries, rate limits, penalties, geolocation, and rules keep the full IP.

See Privacy.

[request_logs]

Per-key request logs (enabled by the API key's requestLogging).

KeyTypeDefaultDescription
retentionduration"72h"Retention of raw logs in the main database; at least 2h. Hourly stats are kept forever. Unused with ClickHouse.
flush_intervalduration"1s"Buffered logs are written at least this often; at least 100ms.
batch_sizeinteger100Buffered logs are also written once this many are pending (1–10000).

See Request logs.

[audit_logs]

Records of logins and management changes (POST /v2/audit-logs/_search, root only).

KeyTypeDefaultDescription
enabledbooleantrueRecord new entries. Existing entries stay searchable and still expire.
retentionduration"90d"Entries older than this are deleted (1d–3650d).

License: recording needs the audit_logs feature. See Audit logs.

[alerts]

Security, system, and usage alerts (POST /v2/alerts/_search) and their deliveries. Each alert rule has its own table below.

KeyTypeDefaultDescription
enabledbooleantrueRaise new alerts. Existing alerts stay searchable and still expire.
retentionduration"90d"Alerts last raised longer ago are deleted (1d–3650d).
cooldownduration"1h"One alert per rule and subject per window (1m–7d); repeats are counted onto it without notifying.
anonymize_ipboolean—Anonymize IPs in alerts and their deliveries. Unset: follows [privacy] anonymize_ip.
webhookstable[][]Webhook endpoints; see [[alerts.webhooks]].

See Alerts.

[[alerts.webhooks]]

Every new alert is POSTed to each endpoint. Repeat the table for more endpoints.

KeyTypeDefaultDescription
urlstring— (required)Endpoint URL; may hold a secret token via expansion.
formatjson | slackjsonjson: the alert object. slack: {"text": …}, for Slack, Mattermost, Rocket.Chat, or Discord's /slack endpoint.
rulesstring[][]Only these alert rules (e.g. brute_force, license_expired); empty: all.
min_severitylow | medium | highlowLowest severity delivered.
secretstring—Signing secret, at least 16 characters. Adds X-Sentinel-Signature: sha256=<hex HMAC-SHA256(secret, "<X-Sentinel-Timestamp>.<body>")>.
headerstable{}Extra request headers, e.g. { Authorization = "Bearer ${ALERTS_WEBHOOK_TOKEN}" }.

See Alerts.

[alerts.email]

Every new alert emailed over SMTP; enabled when host is set.

KeyTypeDefaultDescription
hoststring—SMTP server host.
portintegerby tlsSMTP port. Default 587 for starttls, 465 for implicit, 25 for none.
tlsstarttls | implicit | nonestarttlsstarttls (mandatory), implicit (SMTPS), or none (local relays only).
usernamestring—SMTP AUTH user; unset: no AUTH.
passwordstring—SMTP AUTH password, e.g. "${SMTP_PASSWORD}".
fromstring—Sender, e.g. "Sentinel <alerts@example.com>".
tostring[][]Recipients; one message per alert to all.
rulesstring[][]Only these alert rules; empty: all.
min_severitylow | medium | highlowLowest severity delivered.
ratestring"20/1h"Emails per window across all replicas; alerts beyond it are still stored and delivered elsewhere.
timeoutduration"10s"Connect and per-command timeout (1s–60s).

See Alerts.

[alerts.push]

Web push to subscriptions users create in the web app (/v2/me/push-subscriptions). The signing key is [secrets] vapid_private_key.

KeyTypeDefaultDescription
subjectstring—VAPID contact (mailto: or https:); push is enabled when set.
ratestring"20/1h"Notifications per subscription and window; alerts beyond it are still stored and sent to webhooks.
endpoint_hostsstring[]["fcm.googleapis.com", "push.services.mozilla.com", "push.apple.com", "notify.windows.com"]Allowed push services (including subdomains); []: any HTTPS host.

See Alerts.

[alerts.brute_force]

Failed logins (password, LDAP, OTP, OAuth) from one client IP.

KeyTypeDefaultDescription
enabledbooleantrueEnable this alert rule.
limitstring"3/10m"N failures within the window raise the alert.

[alerts.user_brute_force]

Failed logins for one username from any IPs (distributed guessing).

KeyTypeDefaultDescription
enabledbooleantrueEnable this alert rule.
limitstring"10/1h"N failures within the window raise the alert.

[alerts.verification_failures]

An account's rate of failed POST /v2/verify calls jumps above its baseline.

KeyTypeDefaultDescription
enabledbooleantrueEnable this alert rule.
windowduration"15m"Recent span (5m–6h, whole minutes).
baselineduration"24h"Span before the window that sets the normal rate (1h–168h, whole hours).
factorfloat3.0Alert at this multiple of the baseline's failures per minute or more…
min_failuresinteger50…with at least this many failures in the window.

[alerts.cpu]

Per replica: CPU at or above threshold percent of the available cores for every minute of duration.

KeyTypeDefaultDescription
enabledbooleantrueEnable this alert rule.
thresholdfloat90Percent of available CPU.
durationduration"5m"Sustained span (1m–30m, whole minutes).

[alerts.memory]

Per replica: resident memory at or above threshold percent of the memory limit (cgroup, else host RAM).

KeyTypeDefaultDescription
enabledbooleantrueEnable this alert rule.
thresholdfloat90Percent of the memory limit.
durationduration"5m"Sustained span (1m–30m, whole minutes).

[alerts.server_errors]

Per replica: share of 5xx responses.

KeyTypeDefaultDescription
enabledbooleantrueEnable this alert rule.
thresholdfloat10Percent of responses that are 5xx.
durationduration"5m"Measurement span.
min_requestsinteger100Fewer responses within duration never alert.

[alerts.root_login_country]

A root user signs in from a new country. Needs an [[ip_resolver.providers]] entry.

KeyTypeDefaultDescription
enabledbooleanfalseEnable this alert rule. Off by default because IP geolocation is approximate.

[alerts.download_failures]

Per replica: a remote file fails its check or download several times in a row.

KeyTypeDefaultDescription
enabledbooleantrueEnable this alert rule.
failuresinteger3Consecutive failures (1–100).

[alerts.kv_unavailable]

Per replica: the KV store is unreachable.

KeyTypeDefaultDescription
enabledbooleantrueEnable this alert rule.
durationduration"1m"Outage length before alerting (10s–1h).

[alerts.db_unavailable]

Per replica: the database is unreachable.

KeyTypeDefaultDescription
enabledbooleantrueEnable this alert rule.
durationduration"1m"Outage length before alerting (10s–1h).

[alerts.api_key_networks]

A restricted or full API key used from N distinct networks within a window.

KeyTypeDefaultDescription
enabledbooleantrueEnable this alert rule.
limitstring"10/1h"N distinct networks per window; N at least 2, window 1s–24h.
ipv4_prefixinteger24Prefix length IPv4 addresses are grouped by (8–32). Private and CGNAT addresses count as one network.
ipv6_prefixinteger64Prefix length IPv6 addresses are grouped by (16–128).

[alerts.api_key_denied]

A restricted or full key with a valid secret is denied by its security group.

KeyTypeDefaultDescription
enabledbooleantrueEnable this alert rule.

[alerts.api_key_browser]

A restricted or full key is sent from a browser page (with Origin or Referer).

KeyTypeDefaultDescription
enabledbooleantrueEnable this alert rule.

[alerts.api_key_bearer]

A restricted or full key ID is sent without its secret.

KeyTypeDefaultDescription
enabledbooleantrueEnable this alert rule.

[alerts.api_key_wrong_secret]

Wrong secrets for one restricted or full key.

KeyTypeDefaultDescription
enabledbooleantrueEnable this alert rule.
limitstring"5/10m"N wrong secrets within the window raise the alert.

[alerts.release_critical]

A newer release than the running one is flagged critical, security, or update recommended. Needs [releases].

KeyTypeDefaultDescription
enabledbooleantrueEnable this alert rule.

[alerts.release_outdated]

Newer releases have been out longer than max_age. Needs [releases].

KeyTypeDefaultDescription
enabledbooleantrueEnable this alert rule.
max_ageduration"14d"Age of the oldest newer release (1d–365d).

See Alerts for all alert rules.

[clickhouse]

When url is set, request logs go to ClickHouse instead of the main database.

KeyTypeDefaultDescription
urlstring—ClickHouse HTTP URL, e.g. http://127.0.0.1:8123. https:// (e.g. https://clickhouse.example.com:8443) connects over TLS and verifies the server against the system CA store, tls_extra_ca_certs, and tls_ca.
databasestring"default"Database name; must exist. Sentinel's tables are created in it at startup, or by an administrator with auto_migrate = false.
usernamestring—ClickHouse user.
passwordstring—ClickHouse password, e.g. "${CLICKHOUSE_PASSWORD}".
tls_castring—PEM CA certificate(s) of an https:// server, trusted next to the system CA store, e.g. "${file:/etc/sentinel/clickhouse-ca.pem}".
tls_certstring—PEM client certificate chain, leaf first, for an https:// server. Set together with tls_key.
tls_keystring—PEM private key of tls_cert: PKCS#1, PKCS#8, or SEC1.
raw_retentionduration"90d"Retention of raw logs (_search), 1d–5y. Hourly stats (_stats) are kept 5 years regardless. With auto_migrate = false, a change is logged, not applied.
auto_migratebooleantrueCreate and upgrade the ClickHouse tables at startup. false: startup fails unless they are current, and altcha-sentinel schema sql --clickhouse prints the migration. See Schema migrations.

The tls_* keys need an https:// url; otherwise they stop startup.

License: needs the clickhouse feature, checked at startup; unlicensed, logs stay in the main database. See ClickHouse.

[ip_resolver]

Geolocation and network type of logged requests (countryCode, network) and POST /v2/ip.

KeyTypeDefaultDescription
providerstable[][]Providers in priority order; per field, the first provider with a value wins. See below.

See IP resolvers.

[[ip_resolver.providers]]

One table per provider, selected by type. Every provider has a unique name (a-z, 0-9, _, -).

type = "maxmind"

A MaxMind .mmdb (City, Country, Enterprise, Anonymous-IP, Connection-Type, ASN, ISP), local or downloaded.

KeyTypeDefaultDescription
typestring— (required)"maxmind".
namestring— (required)Unique name; also the remote file name with url.
pathstring—Local .mmdb; relative paths are under data_dir. With Docker, mount the directory, not the file, so updates are seen.
check_intervalduration"1m"With path: reload when the file changes; "0s": never.
urlstring—Instead of path: a .mmdb, or a tar, tar.gz, zip, or gzip archive containing one, stored under <data_dir>/remote-files.
account_idstring—With url: MaxMind account ID (HTTP Basic auth); a number is accepted too.
license_keystring—With url: MaxMind license key, e.g. "${file:/run/secrets/maxmind_license_key}".
headerstable{}With url: other request headers.
schedulestring"@daily"With url: update check schedule.
cache_ttlduration"0s"Per-IP lookup cache; "0s": off.
cache_sizeinteger10000Maximum cached IPs.

type = "ip-api"

The ip-api.com JSON API.

KeyTypeDefaultDescription
typestring— (required)"ip-api".
namestring— (required)Unique name.
keystring—Pro key (HTTPS, unlimited). Unset: the free endpoint (HTTP only, 45 requests/min, non-commercial use).
cache_ttlduration"1h"Per-IP lookup cache; "0s": off.
cache_sizeinteger10000Maximum cached IPs.

type = "ipstack"

The ipstack.com API.

KeyTypeDefaultDescription
typestring— (required)"ipstack".
namestring— (required)Unique name.
keystring— (required)Access key, e.g. "${IPSTACK_COM_KEY}".
httpsbooleantruefalse for the free plan (HTTP only; the key is sent in clear text).
securitybooleanfalseRequest the security module (proxy, Tor, hosting).
cache_ttlduration"1h"Per-IP lookup cache; "0s": off.
cache_sizeinteger10000Maximum cached IPs.

type = "ipinfo"

The ipinfo.io API.

KeyTypeDefaultDescription
typestring— (required)"ipinfo".
namestring— (required)Unique name.
tokenstring— (required)API token (Bearer auth), e.g. "${IPINFO_TOKEN}".
apilite | lookup | legacylitelite: free plan (country, AS name). lookup: Core, Plus, and Max plans. legacy: plans from before 2025.
cache_ttlduration"1h"Per-IP lookup cache; "0s": off.
cache_sizeinteger10000Maximum cached IPs.

type = "ipinfo-mmdb"

An ipinfo.io .mmdb (Lite, Core, Plus, or legacy databases), local or downloaded.

KeyTypeDefaultDescription
typestring— (required)"ipinfo-mmdb".
namestring— (required)Unique name; also the remote file name with url.
pathstring—Local .mmdb; relative paths are under data_dir.
check_intervalduration"1m"With path: reload when the file changes; "0s": never.
urlstring—Instead of path: download URL, e.g. https://ipinfo.io/data/ipinfo_lite.mmdb.
tokenstring—With url: API token (HTTP Basic auth); keep it out of url.
headerstable{}With url: other request headers.
schedulestring"@daily"With url: update check schedule.
cache_ttlduration"0s"Per-IP lookup cache; "0s": off.
cache_sizeinteger10000Maximum cached IPs.

type = "cloudflare"

Cloudflare's CF-IPCountry header (country; T1 means Tor), trusted as is. Only expose the server through Cloudflare. Answers for the request's own client IP only.

KeyTypeDefaultDescription
typestring— (required)"cloudflare".
namestring— (required)Unique name.

type = "headers"

X-IP-* request headers (country-code, country, region, city, lat, lon, asname, mobile, hosting, proxy, tor), accepted only with a matching X-IP-Secret. Answers for the request's own client IP only.

KeyTypeDefaultDescription
typestring— (required)"headers".
namestring— (required)Unique name.
secretstring— (required)Expected X-IP-Secret, e.g. "${IP_HEADERS_SECRET}".

See IP resolvers.

[api_key_cache]

API keys, security groups, and account states held in memory, so widget endpoints authenticate without the database and keep working (stale) while it is down. Changes apply via pub/sub.

KeyTypeDefaultDescription
enabledbooleantruefalse: read key, group, and account from the database on every request.
refresh_intervalduration"10s"Background reload from the database, also its timeout (1s–1h).
max_keysinteger10000Cap on cached keys; keys beyond it are read from the database per request.

See Performance.

[threats]

Threat intelligence: IP lists from threat sources and manual or automatic threat entries.

KeyTypeDefaultDescription
storefile | memoryfilefile: one SQLite index per source under <data_dir>/threats, entry index in a private temporary SQLite file. memory: in-memory SQLite, rebuilt at startup.
sync_intervalduration"5m"Fallback re-read of sources and entries from the database, plus expired-entry deletion (10s–1h).
seed_defaultsbooleantrueCreate the default ALTCHA directory sources on first boot (when there are no threat sources).
signalstable—Automatic threat entries; see [threats.signals].

See Threat intelligence.

[threats.signals]

Automatic threat entries for IPs with repeated auth failures or rate-limit trips (malicious) and honeypot hits (probe).

KeyTypeDefaultDescription
enabledbooleantrueCreate automatic entries.
malicioustable{ limit = "10/5m", expire = "48h" }limit: N signals per IP within the window (1s–24h) create an entry. expire: entry lifetime (1m–30d). Both required when set.
probetable{ limit = "2/5m", expire = "48h" }As malicious. expire is also the default expiry of reports.

See Threat intelligence.

[classifier]

Email, device, IP, and text classification for POST /v2/classifier and POST /v2/verify.

KeyTypeDefaultDescription
dns_timeoutduration"500ms"Per-attempt timeout (2 attempts) of MX and _dmarc TXT lookups through the host resolver (100ms–10s).
dns_cache_ttlduration"1h"Cache lifetime of MX/DMARC answers (1s–24h); failed lookups are cached 30 seconds at most.
dns_cache_sizeinteger10000Maximum cached answers.
disposable, free_providers, trusted_providers, privacy_relays, user_agents, phishingtable—Remote lists; see Classifier lists.
aitable—AI decider; see [classifier.ai].

See Classifier.

Classifier lists

Remote lists under [classifier.<list>], each with the same keys. Lists accept an ALTCHA directory .csv.gz (header dropped), a JSON array, or one entry per line, except where noted.

KeyTypeDefaultDescription
enabledbooleantruefalse: never downloaded; the list stays empty and its rule scores 0.
urlstringALTCHA directory listDownload URL.
schedulestring"@daily"Update check schedule.
max_entriesintegerper listEntries kept (1–10000000); the rest are ignored. Default: 100000 for phishing, 10000 for user_agents (the most-weighted user agents; the rest count as uncommon), no limit for the others.
max_size_mbinteger10Largest download in MiB, before extraction (1–1024). A larger download fails and the stored list is kept.
TableUsed byDefault url
[classifier.disposable]DISPOSABLEhttps://directory.altcha.org/disposable-email-domains.csv.gz
[classifier.free_providers]FREE_PROVIDERhttps://directory.altcha.org/free-email-domains.csv.gz
[classifier.trusted_providers]Well-known providers: never DISPOSABLE, half the FREE_PROVIDER scorehttps://directory.altcha.org/trusted-free-email-providers.csv.gz
[classifier.privacy_relays]PRIVACY_RELAY (e.g. Apple Hide My Email, Firefox Relay)https://directory.altcha.org/email-privacy-relays.csv.gz
[classifier.user_agents]USER_AGENT_HEADER_UNCOMMON; CSV with columns user_agent,weight (header required)https://directory.altcha.org/user-agents.csv.gz
[classifier.phishing]URL_PHISHING, POST /v2/phishing; CSV with column url (header required)https://directory.altcha.org/phishing.csv.gz

See Remote files and Classifier rules.

[classifier.ai]

The AI decider (AI_SPAM, AI_SCAM, AI_ABUSE, AI_GIBBERISH, AI_OFF_TOPIC, AI_CUSTOM). Runs only for security groups that set classifier.ai, and can only raise the score.

KeyTypeDefaultDescription
providertypesafe | openrouter | nonenoneModel provider; none: no AI category.
urlstringprovider'sAPI base; /v1/systemone is appended. Default for typesafe: https://api.typesafe.ai; for openrouter: https://openrouter.ai/api.
api_keystring—Bearer token, e.g. "${OPENROUTER_API_KEY}"; required with the provider's URL.
modelstringprovider'sModel; default the provider's pinned version (e.g. jev-1.14.0 for typesafe).
headerstable{}Extra request headers.
timeoutduration"3s"Per request (500ms–30s); a failed request leaves the category unscored (AI_UNAVAILABLE).
queue_timeoutduration"500ms"Longest wait for a free request slot (10ms–10s).
max_concurrencyinteger16Concurrent requests (1–256).
max_charsinteger4000Characters of text sent, from its start (100–32000). IPs, full email addresses, and the payload are never sent.

See AI decider.

[eml]

POST /v2/eml: parse, authenticate (ARC, DKIM, SPF, DMARC), and classify raw EML messages.

KeyTypeDefaultDescription
enabledbooleantruefalse: the path returns 404.
max_body_sizeinteger5000000Largest accepted message in bytes (1024–100000000); larger bodies get 413.
dns_timeoutduration"1s"Per-attempt timeout (2 attempts) of authentication DNS lookups (X-Authenticate) (100ms–10s).
storage_prefixstring"eml/attachments/"Key prefix of attachments uploaded with X-Attachments-Upload to [storage]; A-Z a-z 0-9 . _ - /. Keys are <prefix><UTC YYYY-MM-DD>/<32 hex><.ext>.
malicious_hashestable—Remote list; see [eml.malicious_hashes].

See Email analysis.

[eml.malicious_hashes]

Known malicious files by SHA-256 (MALICIOUS_ATTACHMENT): a remote file indexed in SQLite under <data_dir>/eml/.

KeyTypeDefaultDescription
enabledbooleantruefalse: never downloaded; the rule scores 0.
urlstringhttps://directory.altcha.org/malicious-file-hashes.csv.gzCSV with column sha256, or one hash per line.
schedulestring"@daily"Update check schedule.
max_entriesinteger—Hashes indexed (1–10000000); the rest are ignored. Unset: no limit.
max_size_mbinteger100Largest download in MiB, before extraction (1–1024). A larger download fails and the stored index is kept.

See Email analysis.

[storage]

Object storage shared by EML attachment uploads and stored snapshots.

KeyTypeDefaultDescription
providers3 | azure | nonenoneStorage backend. With none, X-Attachments-Upload returns 400.
timeoutduration"60s"Per EML upload, list, or delete (1s–10m); a failed upload returns 502 STORAGE_ERROR. Snapshot transfers allow 1 hour.
s3table—See [storage.s3].
azuretable—See [storage.azure].

See Object storage.

[storage.s3]

AWS S3 or an S3-compatible service, with static keys; used when provider = "s3".

KeyTypeDefaultDescription
endpointstringhttps://s3.<region>.amazonaws.comHTTP(S) origin without path, query, or credentials.
regionstring"us-east-1"Region; must not be empty.
bucketstring— (required)Bucket name.
access_key_idstring— (required)Access key ID, e.g. "${AWS_ACCESS_KEY_ID}".
secret_access_keystring— (required)Secret key, e.g. "${AWS_SECRET_ACCESS_KEY}".
path_stylebooleanfalsePath-style URLs (<endpoint>/<bucket>/<key>, e.g. MinIO); always used for IP and localhost endpoints.

[storage.azure]

Azure Blob Storage (or Azurite); used when provider = "azure".

KeyTypeDefaultDescription
connection_stringstring— (required)AccountName + AccountKey (SharedKey) or SharedAccessSignature, plus optional BlobEndpoint, DefaultEndpointsProtocol, EndpointSuffix. Use "${AZURE_STORAGE_CONNECTION_STRING}".
containerstring— (required)Container name.

See Object storage.

[snapshots]

Database snapshots (POST /v2/snapshots, GET /v2/snapshots, root only) of every table except the license tables.

KeyTypeDefaultDescription
enabledbooleantruefalse: /v2/snapshots routes return 404 and no scheduled snapshots run.
identitystring—age X25519 identity (AGE-SECRET-KEY-1…), e.g. "${file:/run/secrets/snapshots.key}". Set: snapshots are encrypted (.zip.age) and, with a [storage] provider, stored there. Unset: plain .zip downloads.
recipientsstring[][]Extra age recipients (age1…) that can decrypt, e.g. an offline recovery key; needs identity.
schedulestring—Cron (UTC) of scheduled snapshots, e.g. "0 3 * * *"; needs identity and a [storage] provider.
keepinteger7Scheduled snapshots kept in storage (0–1000; 0: all). Manual snapshots are never deleted.
storage_prefixstring"snapshots/"Key prefix in [storage]; A-Z a-z 0-9 . _ - /.
exclude_tablesstring[][]Tables left out; allowed: threat_sources, threat_entries, request_logs, request_stats, audit_logs, alerts, similarity_embeddings.
max_upload_sizeinteger1073741824Largest POST /v2/snapshots/_restore body in bytes (1 MiB–100 GiB).

See Snapshots.

[web_bot_auth]

Web Bot Auth (signed agent requests): the security-group agent condition and the request log context.agent.

KeyTypeDefaultDescription
enabledbooleantruefalse: never downloaded, no request is checked, and agent never matches.
urlstringhttps://directory.altcha.org/web-bot-auth.csv.gzTrusted agent keys (name,keyid,agent,operator,category,jwk).
schedulestring"@hourly"Update check schedule.

See Bots and agents.

[pow]

The server side of widget challenges (GET /v2/challenge, POST /v2/challenge).

KeyTypeDefaultDescription
max_memory_costinteger262144KiB (1024–4194304): cap of pow.memoryCost (ARGON2ID) and pow.cost (SCRYPT N, the largest power of 2 within it). Stored rules above it are clamped.
cpusintegerhalf the CPUsChallenge derivations at once, any algorithm (1–1024). Unset: half the available CPUs, at least 1.

See Proof-of-work.

[prometheus]

A Prometheus scrape endpoint on its own listener (altcha_sentinel_* metrics). Scrapes are not counted, logged, or rate limited. The [server] connection timeouts apply here too.

KeyTypeDefaultDescription
enabledbooleanfalseStart the metrics listener.
hoststring (IP)"127.0.0.1"Address to listen on; unauthenticated unless bearer_token is set.
portinteger3001Port to listen on.
pathstring"/metrics"Metrics path; must start with /.
bearer_tokenstring—Required as Authorization: Bearer <token>, e.g. "${PROMETHEUS_TOKEN}". Unset: no auth.
allowed_ipsstring[][]CIDRs or IPs of the TCP peer (not X-Forwarded-For); empty: any.
allowed_hostsstring[][]As in [server], without a forwarded host header; see Allowed hosts. Scrapers usually address the IP, so list it.
tlstable—Serve metrics over HTTPS; see Listener TLS.

See Monitoring.

[telemetry]

OpenTelemetry trace export over OTLP/HTTP (protobuf): a span per API request, database, Redis, and rate-limit spans, and a span per outgoing HTTP call.

KeyTypeDefaultDescription
enabledbooleanfalseExport traces.
endpointstring—Collector URL; /v1/traces is appended. Unset: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, then OTEL_EXPORTER_OTLP_ENDPOINT, then http://localhost:4318.
headerstable{}Export request headers, e.g. { authorization = "Bearer ${OTEL_TOKEN}" }. Empty: OTEL_EXPORTER_OTLP_HEADERS.
service_namestring"altcha-sentinel"Service name of exported spans.
sample_ratiofloat1.0Sampling ratio 0–1, parent-based: an incoming sampled traceparent is always kept.
filterstring"info"Filter directive selecting exported spans, independent of [log] level. Redis and rate-limit spans are debug.
timeoutduration"10s"Export request timeout (1s–60s).

See Monitoring.

[assistant]

The web app's AI assistant: POST /v2/assistant is proxied to the ALTCHA AI service as a signed request carrying the question, chat history, on-screen configuration (never secrets), and the admin's IP and role.

KeyTypeDefaultDescription
enabledbooleantrueServe the assistant.
urlstring"https://eu.altcha.org/ai"Service URL; /sentinel/assistant is appended.
timeoutduration"2m"Longest wait for the next chunk of a reply (10s–10m).

See Air-gapped deployments.

[releases]

The Sentinel release feed (GET /v2/releases, root only) and the release_* alerts.

KeyTypeDefaultDescription
enabledbooleantruefalse: never fetched; no checks or release_* alerts.
urlstring"https://altcha.org/sentinel-releases.xml"RSS 2.0 feed URL. Stable releases only; append ?beta=true to include beta versions.
intervalduration"6h"Scheduled fetch and alert check (1h–7d). GET /v2/releases also refetches in the background when the last attempt is over an hour old.

See Updating.

[code_challenge]

The code image and audio of challenges whose security-group rules set codeChallenge.enabled.

KeyTypeDefaultDescription
tts_dirstring"assets/tts"Voice files (<lang>.pcm + <lang>.json, blip.pcm), relative to the working directory. Without en and blip, no audio URL is issued.
audio_delayduration"3s"Wait before answering GET /v2/challenge/audio/<token>.wav.
min_solve_timeduration"4s"POST /v2/verify rejects a code challenge solved sooner after issue (TOO_FAST); "0s": off.
audio_rate_limitstring"10/5m"Audio requests per client IP, in [rate_limit] syntax (key=uid is rejected at startup); "": unlimited.

See Code challenge.

[similarity]

Training data matching (SIMILARITY, NEAR_DUPLICATE) and campaign detection (CAMPAIGN) in POST /v2/classifier and POST /v2/verify.

KeyTypeDefaultDescription
providerlocal | openai | nonenoneEmbedding model: local (ONNX model, about 135 MB download), openai (OpenAI-compatible API), or none (no semantic matching). Near-duplicates, campaigns, training data, and suggestions work with any provider.
thresholdfloat0.80Default cosine similarity a sample must reach, in (0, 1]; a sample's own threshold overrides it.
negative_marginfloat0.05A match must beat the best negative sample by this much (0–0.5).
near_duplicate_distanceinteger3Maximum SimHash bit distance of a near-duplicate (0–10).
max_chunksinteger8Long texts are embedded in up to this many chunks of about 1000 characters (1–32).
max_samples_per_accountinteger10000Maximum training samples per account.
sync_intervalduration"5m"Fallback re-read of training data (10s–1h).
queue_timeoutduration"2s"Wait for a free model session or API slot (10ms–60s), then EMBEDDING_UNAVAILABLE.
query_prefixstring""Prepended to classified texts (e.g. "query: " for e5 models).
passage_prefixstring""Prepended to training samples (e.g. "passage: ").
local, openai, campaign, builtin, suggestionstable—See the sections below.

See Similarity.

[similarity.local]

The local ONNX embedding model, used when provider = "local". Every replica must use the same model.

KeyTypeDefaultDescription
model_urlstringhttps://huggingface.co/Xenova/paraphrase-multilingual-MiniLM-L12-v2/resolve/main/onnx/model_int8.onnxModel download URL.
tokenizer_urlstringhttps://huggingface.co/Xenova/paraphrase-multilingual-MiniLM-L12-v2/resolve/main/tokenizer.jsonTokenizer download URL.
model_pathstring—Local model file instead of a download; set together with tokenizer_path. Loaded once.
tokenizer_pathstring—Local tokenizer file; set together with model_path.
headerstable{}Headers sent with the downloads, e.g. { Authorization = "Bearer ${HF_TOKEN}" }.
schedulestring"@monthly"Update check schedule of the downloads.
poolingmean | clsmeanEmbedding pooling.
max_tokensinteger256Inputs are truncated to this many tokens (8–8192).
sessionsinteger1Parallel ONNX sessions, each a copy of the model in memory (1–16).
threadsinteger0Intra-op threads per session; 0: ONNX Runtime default.

[similarity.openai]

An OpenAI-compatible embeddings API (OpenAI, or Ollama, vLLM, and TEI through their /v1 endpoints), used when provider = "openai".

KeyTypeDefaultDescription
urlstring"https://api.openai.com/v1"API base URL.
api_keystring—API key, e.g. "${OPENAI_API_KEY}".
modelstring"text-embedding-3-small"Embedding model.
dimensionsinteger—Vector size, for models that support shortened vectors.
headerstable{}Extra request headers.
timeoutduration"10s"Request timeout.
batch_sizeinteger64Texts per request.
max_concurrencyinteger4Concurrent requests.

[similarity.campaign]

Campaign detection (CAMPAIGN): one message, near-duplicates included, sent from many sources to one account.

KeyTypeDefaultDescription
enabledbooleantrueDetect campaigns.
windowduration"1h"Detection window (1m–7d).
min_sourcesinteger5Distinct client IPs within the window (2–10000).
min_charsinteger30Shorter texts are not recorded.

[similarity.builtin]

Curated builtin:* groups from your own CSV (group,label,text,weight), loaded as a remote file.

KeyTypeDefaultDescription
enabledbooleanfalseLoad the groups.
urlstring—CSV URL (.csv or .csv.gz); required when enabled.
schedulestring"@weekly"Update check schedule.

[similarity.suggestions]

A review queue of texts the text rules found to be spam (/v2/training-suggestions). Stores message text.

KeyTypeDefaultDescription
enabledbooleanfalseCollect suggestions.
retentionduration"7d"Queued suggestions older than this are deleted (1h–90d).
max_per_accountinteger1000Soft cap per account and replica; new texts are dropped when full.

See Similarity.

Start typing to search...

↑ ↓ Navigate ↵ Select