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:
| Syntax | Result |
|---|---|
"${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
| Section | Purpose |
|---|---|
| Top level | Data 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.
| Key | Type | Default | Description |
|---|---|---|---|
tls_extra_ca_certs | string | — | 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_dir | string | "./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.
| Key | Type | Default | Description |
|---|---|---|---|
host | string (IP) | "0.0.0.0" | Address to listen on. |
port | integer | 3000 | Port to listen on. |
trusted_proxies | string[] | [] | 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_header | string | — | 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_header | string | — | 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_url | string | — | 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_hosts | string[] | [] | Hosts this listener answers /v2 for; others get 421. See Allowed hosts. Empty: any host. |
health_allowed_ips | string[] | private networks | CIDRs 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_compat | boolean | false | Serve /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. |
tls | table | — | Serve this listener over HTTPS: { cert = "…", key = "…" }. See Listener TLS. Unset: plain HTTP. |
idle_timeout | duration | "620s" | Every listener: a connection with no request in flight this long is closed (1s–24h). See Connection timeouts. |
header_read_timeout | duration | "30s" | Every listener: longest wait for a complete request head (1s–10m). |
body_read_timeout | duration | "30s" | Every listener: longest wait for the next part of a request body (1s–10m). |
write_timeout | duration | "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 ofdomainbut notdomainitself. 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_headerwhen set and sent by a trusted peer, elseHost, else the HTTP/2:authority.[prometheus]has no forwarded host header. A request without a host gets421too. Withforwarded_host_headerand emptytrusted_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/v1aliases) is checked.GET /,GET /.health, and the honeypot paths answer any host, so load balancer probes andhealthcheck, 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.
200with"status": "healthy"when every check isok;503with"unhealthy"otherwise. - Checks.
kvis the KV store (Redis or the built-in KV),dbthe database, andclickhouseis 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
storageofGET /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'srequests. - 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 get403 IP_NOT_ALLOWED. So does a request withX-Forwarded-For,X-Real-IP,Forwarded, or theclient_ip_headerfrom a peer outsidetrusted_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).
| Key | Type | Default | Description |
|---|---|---|---|
cert | string | — (required) | PEM certificate chain, leaf certificate first. |
key | string | — (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/nonrootin the image), not tosentinel.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 …orserver.tls: certificate and key).doctor --config-onlyruns the same check and reports it asFAIL config.valid (server.tls). A listener that isn't enabled doesn't read its files, and neither doesdoctor. - 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].
| Key | Starts | When it expires |
|---|---|---|
idle_timeout | When the connection has no request in flight | The 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_timeout | On a new connection, or at the first byte of the next request on an idle HTTP/1.1 connection | The connection is dropped. HTTP/2 request heads are bounded by idle_timeout instead. |
body_read_timeout | At each read of the request body that waits for data | The 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_timeout | When a response waits on the client: a blocked write, or HTTP/2 flow control holding the next part | The 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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | false | Start this listener. |
host | string (IP) | "0.0.0.0" | Address to listen on. |
port | integer | 3003 | Port to listen on. |
trusted_proxies | string[] | [] | As in [server], for this listener only. |
client_ip_header | string | — | As in [server], for this listener only. |
forwarded_host_header | string | — | As in [server], for this listener only. |
allowed_hosts | string[] | [] | As in [server], for this listener only; see Allowed hosts. |
base_url | string | — | Public URL of this listener; its path prefixes the widget URLs answered here. |
verify_signature | boolean | false | Also serve POST /v2/verify/signature. |
tls | table | — | 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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | false | Start this listener. |
host | string (IP) | "127.0.0.1" | Address to listen on. |
port | integer | 3002 | Port to listen on. |
dir | string | — | 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_ips | string[] | [] | 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_reference | boolean | true | Serve the public API reference page, rendering GET /v2/openapi.json. |
trusted_proxies | string[] | [] | As in [server], for this listener only. |
client_ip_header | string | — | As in [server], for this listener only. |
forwarded_host_header | string | — | As in [server], for this listener only. |
allowed_hosts | string[] | [] | As in [server], for this listener only, and checked for its static files too; see Allowed hosts. |
base_url | string | — | 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). |
tls | table | — | 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.
| Key | Type | Default | Description |
|---|---|---|---|
level | string | "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"). |
format | string | "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.
| Key | Type | Default | Description |
|---|---|---|---|
url | string | sqlite:<data_dir>/sentinel.db | Connection 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. |
token | string | — | Access token; ExotDB server only. |
name | string | "sentinel" | Database name; ExotDB server only. |
table_prefix | string | "" | 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_mode | string | "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_ca | string | — | PEM CA certificate(s) of an https:// ExotDB server, trusted next to the system CA store. |
tls_cert | string | — | PEM client certificate chain, leaf first, for an https:// ExotDB server. Set together with tls_key. |
tls_key | string | — | PEM private key of tls_cert: PKCS#1, PKCS#8, or SEC1. |
pool_min | integer | 2 | Connections the pool keeps open. At most pool_max. |
pool_max | integer | 20 | Most 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_timeout | duration | "5s" | Longest wait for a free connection; then the database call fails. "0s" waits forever. |
max_lifetime | duration | "30m" | A connection is replaced after this long. "0s": never. Not SQLite. |
idle_timeout | duration | "10m" | A connection idle this long is closed. "0s": never. Not SQLite. |
request_timeout | duration | "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_migrate | boolean | true | Create 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.
| Backend | Parameters | Default |
|---|---|---|
| PostgreSQL | sslmode (disable, allow, prefer, require, verify-ca, verify-full), sslrootcert, sslcert, sslkey | prefer: TLS when the server offers it, without certificate verification |
| MySQL, MariaDB | ssl-mode (DISABLED, PREFERRED, REQUIRED, VERIFY_CA, VERIFY_IDENTITY), ssl-ca, ssl-cert, ssl-key | PREFERRED: TLS when the server offers it, without certificate verification |
| SQL Server | trust_cert_ca (a CA file), trust_cert=true (skip verification; not with trust_cert_ca), encrypt=false (no TLS) | Encrypted and verified |
| Oracle | In the connect string, tnsnames.ora, or sqlnet.ora; see Oracle TLS | Plain 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.ssoMount 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.
| Key | Type | Default | Description |
|---|---|---|---|
nodes | string[] | [] | 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. |
builtin | string | "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. |
synchronous | string | "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_prefix | string | "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. |
timeout | duration | "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_ca | string | — | PEM CA certificate(s) of rediss:// nodes, trusted next to the system CA store. |
tls_cert | string | — | PEM client certificate chain, leaf first, for rediss:// nodes. Set together with tls_key. |
tls_key | string | — | 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.
| Key | Type | Default | Description |
|---|---|---|---|
nodes | string[] | — | 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. |
master | string | — | Required. The master name the Sentinels monitor (sentinel monitor <name> …). |
username | string | — | ACL user for the master. Unset: the default user. |
password | string | — | 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.
| Key | Type | Default | Description |
|---|---|---|---|
jwt_secret | string | generated | Session token signing secret; at least 24 characters. |
altcha_hmac_secret | string | generated | Signing secret of the admin sign-in challenge; at least 24 characters. Widget challenges are signed with the API key's secret. |
encryption_key | string | generated | Encrypts stored API key and TOTP secrets and the OAuth state cookie, and derives the EDK; 64 hex characters. |
vapid_private_key | string | generated 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.
| Key | Type | Default | Description |
|---|---|---|---|
file | string | — | Path of a signed license file, verified offline; imported at startup when newer than the stored license. |
key | string | — | Online activation key (SENT-…); enables activation and daily refresh. Never stored. Not with file. |
server | string | "https://license.altcha.org" | License server for activation and refresh. Only the URL can be changed; it cannot be turned off. |
standby | boolean | false | Start 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.
| Key | Type | Default | Description |
|---|---|---|---|
jwt_issuer | string | "ALTCHA_SENTINEL" | Issuer claim of session tokens. |
jwt_ttl | duration | "24h" | Session token lifetime. |
verify_altcha | boolean | true | Require the ALTCHA check on login. false is for testing only. |
password_login | boolean | true | false disables POST /v2/auth/login for every user; requires [auth.oauth.*] or [auth.ldap]. |
block_threats | boolean | true | Refuse 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_url | string | — | 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). |
oauth | table | — | OAuth providers; see the [auth.oauth.*] sections below. |
ldap | table | — | 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.
| Key | Type | Default | Description |
|---|---|---|---|
name | string | provider name | Button label. |
client_id | string | — (required) | OAuth client ID. |
client_secret | string | — (required) | OAuth client secret, e.g. "${AZURE_CLIENT_SECRET}". |
tenant_id | string | — (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).
| Key | Type | Default | Description |
|---|---|---|---|
name | string | provider name | Button label. |
client_id | string | — (required) | OAuth client ID. |
client_secret | string | — (required) | OAuth client secret, e.g. "${GOOGLE_CLIENT_SECRET}". |
hosted_domain | string | — (required) | Required hd claim, e.g. "example.com". |
License: needs the oauth feature. See Sign-in.
[auth.oauth.keycloak]
Keycloak (OpenID Connect) sign-in.
| Key | Type | Default | Description |
|---|---|---|---|
name | string | provider name | Button label. |
client_id | string | — (required) | OAuth client ID. |
client_secret | string | — (required) | OAuth client secret, e.g. "${KEYCLOAK_CLIENT_SECRET}". |
issuer | string | — (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.
| Key | Type | Default | Description |
|---|---|---|---|
name | string | provider name | Button label. |
client_id | string | — (required) | OAuth client ID. |
client_secret | string | — (required) | OAuth client secret, e.g. "${OKTA_CLIENT_SECRET}". |
issuer | string | — (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).
| Key | Type | Default | Description |
|---|---|---|---|
name | string | "LDAP" | Button label. |
url | string | — (required) | ldap:// or ldaps:// URL, host and optional port only. |
user_dn | string | — | Direct bind: a bind-DN template containing USERNAME, or a base so the DN becomes <username_attribute>=<value>,<user_dn>. |
username_attribute | string | "uid" | Attribute naming the user in the DN and search filter. |
username_template | string | — | Value used in the DN and search filter, e.g. "USERNAME@corp.example". Unset: the username as typed. |
admin_dn | string | — | Search-then-bind: service account DN. |
admin_password | string | — | Service account password, e.g. "${LDAP_ADMIN_PASSWORD}". |
user_search_base | string | — | Base DN of the user search; also read for the display name (cn) after a direct bind. |
starttls | boolean | false | Use StartTLS on ldap://. |
reject_unauthorized | boolean | true | false skips server certificate verification. |
tls_ca | string | — | 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_cert | string | — | PEM client certificate chain, leaf first. |
tls_key | string | — | PEM client key (PKCS#1, PKCS#8, or SEC1). |
group_search_base | string | — | Base DN of the group search; set together with allowed_groups. |
group_class | string | "groupOfNames" | Object class of groups (posixGroup for memberUid groups). |
group_member_attribute | string | "member" | Group attribute listing members (memberUid for posixGroup). |
group_member_user_attribute | string | "dn" | User value stored in the member attribute: dn, or a user attribute such as uid. |
allowed_groups | string[] | [] | 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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | The only way to disable the global limit. |
global | string | "100/1m" | Comma-separated points/duration[(params)] limits, e.g. "100/1m,1000/1h(sliding)". |
memory_fallback | boolean | true | Limit in memory while the KV store is down. false: fail open. |
memory_max_keys | integer | 100000 | Maximum keys of the in-memory fallback. |
redis_fail_threshold | integer | 3 | Consecutive 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.
| Key | Type | Default | Description |
|---|---|---|---|
seed_header | string | — | Header with a per-user seed set by your proxy (e.g. a user ID); trusted like client_ip_header. |
seed_cookie | string | — | Name of a signed seed cookie: <seed>.<hex HMAC-SHA256(seed_cookie_secret, seed)>. Same-site deployments only. |
seed_cookie_secret | string | — | Cookie signing secret, at least 24 characters; required with seed_cookie. Use "${EDK_SEED_COOKIE_SECRET}". |
time_zone | string | "UTC" | IANA time zone whose midnight rotates EDKs; pick one where midnight is low traffic. |
See Rate limiting.
[inspect]
The GET /v2/inspect endpoint.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Serve GET /v2/inspect. |
security_rules | boolean | false | Include 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.
| Key | Type | Default | Description |
|---|---|---|---|
ttl | duration | "30m" | A penalty expires this long after its last increase; at least 1s. |
See Security rules.
[bootstrap]
First-boot setup.
| Key | Type | Default | Description |
|---|---|---|---|
root_password | string | random (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.
| Key | Type | Default | Description |
|---|---|---|---|
anonymize_ip | boolean | false | Zero 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).
| Key | Type | Default | Description |
|---|---|---|---|
retention | duration | "72h" | Retention of raw logs in the main database; at least 2h. Hourly stats are kept forever. Unused with ClickHouse. |
flush_interval | duration | "1s" | Buffered logs are written at least this often; at least 100ms. |
batch_size | integer | 100 | Buffered 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).
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Record new entries. Existing entries stay searchable and still expire. |
retention | duration | "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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Raise new alerts. Existing alerts stay searchable and still expire. |
retention | duration | "90d" | Alerts last raised longer ago are deleted (1d–3650d). |
cooldown | duration | "1h" | One alert per rule and subject per window (1m–7d); repeats are counted onto it without notifying. |
anonymize_ip | boolean | — | Anonymize IPs in alerts and their deliveries. Unset: follows [privacy] anonymize_ip. |
webhooks | table[] | [] | Webhook endpoints; see [[alerts.webhooks]]. |
See Alerts.
[[alerts.webhooks]]
Every new alert is POSTed to each endpoint. Repeat the table for more endpoints.
| Key | Type | Default | Description |
|---|---|---|---|
url | string | — (required) | Endpoint URL; may hold a secret token via expansion. |
format | json | slack | json | json: the alert object. slack: {"text": …}, for Slack, Mattermost, Rocket.Chat, or Discord's /slack endpoint. |
rules | string[] | [] | Only these alert rules (e.g. brute_force, license_expired); empty: all. |
min_severity | low | medium | high | low | Lowest severity delivered. |
secret | string | — | Signing secret, at least 16 characters. Adds X-Sentinel-Signature: sha256=<hex HMAC-SHA256(secret, "<X-Sentinel-Timestamp>.<body>")>. |
headers | table | {} | 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.
| Key | Type | Default | Description |
|---|---|---|---|
host | string | — | SMTP server host. |
port | integer | by tls | SMTP port. Default 587 for starttls, 465 for implicit, 25 for none. |
tls | starttls | implicit | none | starttls | starttls (mandatory), implicit (SMTPS), or none (local relays only). |
username | string | — | SMTP AUTH user; unset: no AUTH. |
password | string | — | SMTP AUTH password, e.g. "${SMTP_PASSWORD}". |
from | string | — | Sender, e.g. "Sentinel <alerts@example.com>". |
to | string[] | [] | Recipients; one message per alert to all. |
rules | string[] | [] | Only these alert rules; empty: all. |
min_severity | low | medium | high | low | Lowest severity delivered. |
rate | string | "20/1h" | Emails per window across all replicas; alerts beyond it are still stored and delivered elsewhere. |
timeout | duration | "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.
| Key | Type | Default | Description |
|---|---|---|---|
subject | string | — | VAPID contact (mailto: or https:); push is enabled when set. |
rate | string | "20/1h" | Notifications per subscription and window; alerts beyond it are still stored and sent to webhooks. |
endpoint_hosts | string[] | ["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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable this alert rule. |
limit | string | "3/10m" | N failures within the window raise the alert. |
[alerts.user_brute_force]
Failed logins for one username from any IPs (distributed guessing).
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable this alert rule. |
limit | string | "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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable this alert rule. |
window | duration | "15m" | Recent span (5m–6h, whole minutes). |
baseline | duration | "24h" | Span before the window that sets the normal rate (1h–168h, whole hours). |
factor | float | 3.0 | Alert at this multiple of the baseline's failures per minute or more… |
min_failures | integer | 50 | …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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable this alert rule. |
threshold | float | 90 | Percent of available CPU. |
duration | duration | "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).
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable this alert rule. |
threshold | float | 90 | Percent of the memory limit. |
duration | duration | "5m" | Sustained span (1m–30m, whole minutes). |
[alerts.server_errors]
Per replica: share of 5xx responses.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable this alert rule. |
threshold | float | 10 | Percent of responses that are 5xx. |
duration | duration | "5m" | Measurement span. |
min_requests | integer | 100 | Fewer responses within duration never alert. |
[alerts.root_login_country]
A root user signs in from a new country. Needs an [[ip_resolver.providers]] entry.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | false | Enable 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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable this alert rule. |
failures | integer | 3 | Consecutive failures (1–100). |
[alerts.kv_unavailable]
Per replica: the KV store is unreachable.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable this alert rule. |
duration | duration | "1m" | Outage length before alerting (10s–1h). |
[alerts.db_unavailable]
Per replica: the database is unreachable.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable this alert rule. |
duration | duration | "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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable this alert rule. |
limit | string | "10/1h" | N distinct networks per window; N at least 2, window 1s–24h. |
ipv4_prefix | integer | 24 | Prefix length IPv4 addresses are grouped by (8–32). Private and CGNAT addresses count as one network. |
ipv6_prefix | integer | 64 | Prefix 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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable this alert rule. |
[alerts.api_key_browser]
A restricted or full key is sent from a browser page (with Origin or Referer).
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable this alert rule. |
[alerts.api_key_bearer]
A restricted or full key ID is sent without its secret.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable this alert rule. |
[alerts.api_key_wrong_secret]
Wrong secrets for one restricted or full key.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable this alert rule. |
limit | string | "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].
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable this alert rule. |
[alerts.release_outdated]
Newer releases have been out longer than max_age. Needs [releases].
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable this alert rule. |
max_age | duration | "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.
| Key | Type | Default | Description |
|---|---|---|---|
url | string | — | 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. |
database | string | "default" | Database name; must exist. Sentinel's tables are created in it at startup, or by an administrator with auto_migrate = false. |
username | string | — | ClickHouse user. |
password | string | — | ClickHouse password, e.g. "${CLICKHOUSE_PASSWORD}". |
tls_ca | string | — | PEM CA certificate(s) of an https:// server, trusted next to the system CA store, e.g. "${file:/etc/sentinel/clickhouse-ca.pem}". |
tls_cert | string | — | PEM client certificate chain, leaf first, for an https:// server. Set together with tls_key. |
tls_key | string | — | PEM private key of tls_cert: PKCS#1, PKCS#8, or SEC1. |
raw_retention | duration | "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_migrate | boolean | true | Create 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.
| Key | Type | Default | Description |
|---|---|---|---|
providers | table[] | [] | 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.
| Key | Type | Default | Description |
|---|---|---|---|
type | string | — (required) | "maxmind". |
name | string | — (required) | Unique name; also the remote file name with url. |
path | string | — | Local .mmdb; relative paths are under data_dir. With Docker, mount the directory, not the file, so updates are seen. |
check_interval | duration | "1m" | With path: reload when the file changes; "0s": never. |
url | string | — | Instead of path: a .mmdb, or a tar, tar.gz, zip, or gzip archive containing one, stored under <data_dir>/remote-files. |
account_id | string | — | With url: MaxMind account ID (HTTP Basic auth); a number is accepted too. |
license_key | string | — | With url: MaxMind license key, e.g. "${file:/run/secrets/maxmind_license_key}". |
headers | table | {} | With url: other request headers. |
schedule | string | "@daily" | With url: update check schedule. |
cache_ttl | duration | "0s" | Per-IP lookup cache; "0s": off. |
cache_size | integer | 10000 | Maximum cached IPs. |
type = "ip-api"
The ip-api.com JSON API.
| Key | Type | Default | Description |
|---|---|---|---|
type | string | — (required) | "ip-api". |
name | string | — (required) | Unique name. |
key | string | — | Pro key (HTTPS, unlimited). Unset: the free endpoint (HTTP only, 45 requests/min, non-commercial use). |
cache_ttl | duration | "1h" | Per-IP lookup cache; "0s": off. |
cache_size | integer | 10000 | Maximum cached IPs. |
type = "ipstack"
The ipstack.com API.
| Key | Type | Default | Description |
|---|---|---|---|
type | string | — (required) | "ipstack". |
name | string | — (required) | Unique name. |
key | string | — (required) | Access key, e.g. "${IPSTACK_COM_KEY}". |
https | boolean | true | false for the free plan (HTTP only; the key is sent in clear text). |
security | boolean | false | Request the security module (proxy, Tor, hosting). |
cache_ttl | duration | "1h" | Per-IP lookup cache; "0s": off. |
cache_size | integer | 10000 | Maximum cached IPs. |
type = "ipinfo"
The ipinfo.io API.
| Key | Type | Default | Description |
|---|---|---|---|
type | string | — (required) | "ipinfo". |
name | string | — (required) | Unique name. |
token | string | — (required) | API token (Bearer auth), e.g. "${IPINFO_TOKEN}". |
api | lite | lookup | legacy | lite | lite: free plan (country, AS name). lookup: Core, Plus, and Max plans. legacy: plans from before 2025. |
cache_ttl | duration | "1h" | Per-IP lookup cache; "0s": off. |
cache_size | integer | 10000 | Maximum cached IPs. |
type = "ipinfo-mmdb"
An ipinfo.io .mmdb (Lite, Core, Plus, or legacy databases), local or downloaded.
| Key | Type | Default | Description |
|---|---|---|---|
type | string | — (required) | "ipinfo-mmdb". |
name | string | — (required) | Unique name; also the remote file name with url. |
path | string | — | Local .mmdb; relative paths are under data_dir. |
check_interval | duration | "1m" | With path: reload when the file changes; "0s": never. |
url | string | — | Instead of path: download URL, e.g. https://ipinfo.io/data/ipinfo_lite.mmdb. |
token | string | — | With url: API token (HTTP Basic auth); keep it out of url. |
headers | table | {} | With url: other request headers. |
schedule | string | "@daily" | With url: update check schedule. |
cache_ttl | duration | "0s" | Per-IP lookup cache; "0s": off. |
cache_size | integer | 10000 | Maximum 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.
| Key | Type | Default | Description |
|---|---|---|---|
type | string | — (required) | "cloudflare". |
name | string | — (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.
| Key | Type | Default | Description |
|---|---|---|---|
type | string | — (required) | "headers". |
name | string | — (required) | Unique name. |
secret | string | — (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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | false: read key, group, and account from the database on every request. |
refresh_interval | duration | "10s" | Background reload from the database, also its timeout (1s–1h). |
max_keys | integer | 10000 | Cap 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.
| Key | Type | Default | Description |
|---|---|---|---|
store | file | memory | file | file: 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_interval | duration | "5m" | Fallback re-read of sources and entries from the database, plus expired-entry deletion (10s–1h). |
seed_defaults | boolean | true | Create the default ALTCHA directory sources on first boot (when there are no threat sources). |
signals | table | — | 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).
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Create automatic entries. |
malicious | table | { 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. |
probe | table | { 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.
| Key | Type | Default | Description |
|---|---|---|---|
dns_timeout | duration | "500ms" | Per-attempt timeout (2 attempts) of MX and _dmarc TXT lookups through the host resolver (100ms–10s). |
dns_cache_ttl | duration | "1h" | Cache lifetime of MX/DMARC answers (1s–24h); failed lookups are cached 30 seconds at most. |
dns_cache_size | integer | 10000 | Maximum cached answers. |
disposable, free_providers, trusted_providers, privacy_relays, user_agents, phishing | table | — | Remote lists; see Classifier lists. |
ai | table | — | 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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | false: never downloaded; the list stays empty and its rule scores 0. |
url | string | ALTCHA directory list | Download URL. |
schedule | string | "@daily" | Update check schedule. |
max_entries | integer | per list | Entries 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_mb | integer | 10 | Largest download in MiB, before extraction (1–1024). A larger download fails and the stored list is kept. |
| Table | Used by | Default url |
|---|---|---|
[classifier.disposable] | DISPOSABLE | https://directory.altcha.org/disposable-email-domains.csv.gz |
[classifier.free_providers] | FREE_PROVIDER | https://directory.altcha.org/free-email-domains.csv.gz |
[classifier.trusted_providers] | Well-known providers: never DISPOSABLE, half the FREE_PROVIDER score | https://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.
| Key | Type | Default | Description |
|---|---|---|---|
provider | typesafe | openrouter | none | none | Model provider; none: no AI category. |
url | string | provider's | API base; /v1/systemone is appended. Default for typesafe: https://api.typesafe.ai; for openrouter: https://openrouter.ai/api. |
api_key | string | — | Bearer token, e.g. "${OPENROUTER_API_KEY}"; required with the provider's URL. |
model | string | provider's | Model; default the provider's pinned version (e.g. jev-1.14.0 for typesafe). |
headers | table | {} | Extra request headers. |
timeout | duration | "3s" | Per request (500ms–30s); a failed request leaves the category unscored (AI_UNAVAILABLE). |
queue_timeout | duration | "500ms" | Longest wait for a free request slot (10ms–10s). |
max_concurrency | integer | 16 | Concurrent requests (1–256). |
max_chars | integer | 4000 | Characters 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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | false: the path returns 404. |
max_body_size | integer | 5000000 | Largest accepted message in bytes (1024–100000000); larger bodies get 413. |
dns_timeout | duration | "1s" | Per-attempt timeout (2 attempts) of authentication DNS lookups (X-Authenticate) (100ms–10s). |
storage_prefix | string | "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_hashes | table | — | 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/.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | false: never downloaded; the rule scores 0. |
url | string | https://directory.altcha.org/malicious-file-hashes.csv.gz | CSV with column sha256, or one hash per line. |
schedule | string | "@daily" | Update check schedule. |
max_entries | integer | — | Hashes indexed (1–10000000); the rest are ignored. Unset: no limit. |
max_size_mb | integer | 100 | Largest 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.
| Key | Type | Default | Description |
|---|---|---|---|
provider | s3 | azure | none | none | Storage backend. With none, X-Attachments-Upload returns 400. |
timeout | duration | "60s" | Per EML upload, list, or delete (1s–10m); a failed upload returns 502 STORAGE_ERROR. Snapshot transfers allow 1 hour. |
s3 | table | — | See [storage.s3]. |
azure | table | — | See [storage.azure]. |
See Object storage.
[storage.s3]
AWS S3 or an S3-compatible service, with static keys; used when provider = "s3".
| Key | Type | Default | Description |
|---|---|---|---|
endpoint | string | https://s3.<region>.amazonaws.com | HTTP(S) origin without path, query, or credentials. |
region | string | "us-east-1" | Region; must not be empty. |
bucket | string | — (required) | Bucket name. |
access_key_id | string | — (required) | Access key ID, e.g. "${AWS_ACCESS_KEY_ID}". |
secret_access_key | string | — (required) | Secret key, e.g. "${AWS_SECRET_ACCESS_KEY}". |
path_style | boolean | false | Path-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".
| Key | Type | Default | Description |
|---|---|---|---|
connection_string | string | — (required) | AccountName + AccountKey (SharedKey) or SharedAccessSignature, plus optional BlobEndpoint, DefaultEndpointsProtocol, EndpointSuffix. Use "${AZURE_STORAGE_CONNECTION_STRING}". |
container | string | — (required) | Container name. |
See Object storage.
[snapshots]
Database snapshots (POST /v2/snapshots, GET /v2/snapshots, root only) of every table except the license tables.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | false: /v2/snapshots routes return 404 and no scheduled snapshots run. |
identity | string | — | 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. |
recipients | string[] | [] | Extra age recipients (age1…) that can decrypt, e.g. an offline recovery key; needs identity. |
schedule | string | — | Cron (UTC) of scheduled snapshots, e.g. "0 3 * * *"; needs identity and a [storage] provider. |
keep | integer | 7 | Scheduled snapshots kept in storage (0–1000; 0: all). Manual snapshots are never deleted. |
storage_prefix | string | "snapshots/" | Key prefix in [storage]; A-Z a-z 0-9 . _ - /. |
exclude_tables | string[] | [] | Tables left out; allowed: threat_sources, threat_entries, request_logs, request_stats, audit_logs, alerts, similarity_embeddings. |
max_upload_size | integer | 1073741824 | Largest 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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | false: never downloaded, no request is checked, and agent never matches. |
url | string | https://directory.altcha.org/web-bot-auth.csv.gz | Trusted agent keys (name,keyid,agent,operator,category,jwk). |
schedule | string | "@hourly" | Update check schedule. |
See Bots and agents.
[pow]
The server side of widget challenges (GET /v2/challenge, POST /v2/challenge).
| Key | Type | Default | Description |
|---|---|---|---|
max_memory_cost | integer | 262144 | KiB (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. |
cpus | integer | half the CPUs | Challenge 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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | false | Start the metrics listener. |
host | string (IP) | "127.0.0.1" | Address to listen on; unauthenticated unless bearer_token is set. |
port | integer | 3001 | Port to listen on. |
path | string | "/metrics" | Metrics path; must start with /. |
bearer_token | string | — | Required as Authorization: Bearer <token>, e.g. "${PROMETHEUS_TOKEN}". Unset: no auth. |
allowed_ips | string[] | [] | CIDRs or IPs of the TCP peer (not X-Forwarded-For); empty: any. |
allowed_hosts | string[] | [] | As in [server], without a forwarded host header; see Allowed hosts. Scrapers usually address the IP, so list it. |
tls | table | — | 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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | false | Export traces. |
endpoint | string | — | Collector URL; /v1/traces is appended. Unset: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, then OTEL_EXPORTER_OTLP_ENDPOINT, then http://localhost:4318. |
headers | table | {} | Export request headers, e.g. { authorization = "Bearer ${OTEL_TOKEN}" }. Empty: OTEL_EXPORTER_OTLP_HEADERS. |
service_name | string | "altcha-sentinel" | Service name of exported spans. |
sample_ratio | float | 1.0 | Sampling ratio 0–1, parent-based: an incoming sampled traceparent is always kept. |
filter | string | "info" | Filter directive selecting exported spans, independent of [log] level. Redis and rate-limit spans are debug. |
timeout | duration | "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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Serve the assistant. |
url | string | "https://eu.altcha.org/ai" | Service URL; /sentinel/assistant is appended. |
timeout | duration | "2m" | Longest wait for the next chunk of a reply (10s–10m). |
[releases]
The Sentinel release feed (GET /v2/releases, root only) and the release_* alerts.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | false: never fetched; no checks or release_* alerts. |
url | string | "https://altcha.org/sentinel-releases.xml" | RSS 2.0 feed URL. Stable releases only; append ?beta=true to include beta versions. |
interval | duration | "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.
| Key | Type | Default | Description |
|---|---|---|---|
tts_dir | string | "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_delay | duration | "3s" | Wait before answering GET /v2/challenge/audio/<token>.wav. |
min_solve_time | duration | "4s" | POST /v2/verify rejects a code challenge solved sooner after issue (TOO_FAST); "0s": off. |
audio_rate_limit | string | "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.
| Key | Type | Default | Description |
|---|---|---|---|
provider | local | openai | none | none | Embedding 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. |
threshold | float | 0.80 | Default cosine similarity a sample must reach, in (0, 1]; a sample's own threshold overrides it. |
negative_margin | float | 0.05 | A match must beat the best negative sample by this much (0–0.5). |
near_duplicate_distance | integer | 3 | Maximum SimHash bit distance of a near-duplicate (0–10). |
max_chunks | integer | 8 | Long texts are embedded in up to this many chunks of about 1000 characters (1–32). |
max_samples_per_account | integer | 10000 | Maximum training samples per account. |
sync_interval | duration | "5m" | Fallback re-read of training data (10s–1h). |
queue_timeout | duration | "2s" | Wait for a free model session or API slot (10ms–60s), then EMBEDDING_UNAVAILABLE. |
query_prefix | string | "" | Prepended to classified texts (e.g. "query: " for e5 models). |
passage_prefix | string | "" | Prepended to training samples (e.g. "passage: "). |
local, openai, campaign, builtin, suggestions | table | — | See the sections below. |
See Similarity.
[similarity.local]
The local ONNX embedding model, used when provider = "local". Every replica must use the same model.
| Key | Type | Default | Description |
|---|---|---|---|
model_url | string | https://huggingface.co/Xenova/paraphrase-multilingual-MiniLM-L12-v2/resolve/main/onnx/model_int8.onnx | Model download URL. |
tokenizer_url | string | https://huggingface.co/Xenova/paraphrase-multilingual-MiniLM-L12-v2/resolve/main/tokenizer.json | Tokenizer download URL. |
model_path | string | — | Local model file instead of a download; set together with tokenizer_path. Loaded once. |
tokenizer_path | string | — | Local tokenizer file; set together with model_path. |
headers | table | {} | Headers sent with the downloads, e.g. { Authorization = "Bearer ${HF_TOKEN}" }. |
schedule | string | "@monthly" | Update check schedule of the downloads. |
pooling | mean | cls | mean | Embedding pooling. |
max_tokens | integer | 256 | Inputs are truncated to this many tokens (8–8192). |
sessions | integer | 1 | Parallel ONNX sessions, each a copy of the model in memory (1–16). |
threads | integer | 0 | Intra-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".
| Key | Type | Default | Description |
|---|---|---|---|
url | string | "https://api.openai.com/v1" | API base URL. |
api_key | string | — | API key, e.g. "${OPENAI_API_KEY}". |
model | string | "text-embedding-3-small" | Embedding model. |
dimensions | integer | — | Vector size, for models that support shortened vectors. |
headers | table | {} | Extra request headers. |
timeout | duration | "10s" | Request timeout. |
batch_size | integer | 64 | Texts per request. |
max_concurrency | integer | 4 | Concurrent requests. |
[similarity.campaign]
Campaign detection (CAMPAIGN): one message, near-duplicates included, sent from many sources to one account.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Detect campaigns. |
window | duration | "1h" | Detection window (1m–7d). |
min_sources | integer | 5 | Distinct client IPs within the window (2–10000). |
min_chars | integer | 30 | Shorter texts are not recorded. |
[similarity.builtin]
Curated builtin:* groups from your own CSV (group,label,text,weight), loaded as a remote file.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | false | Load the groups. |
url | string | — | CSV URL (.csv or .csv.gz); required when enabled. |
schedule | string | "@weekly" | Update check schedule. |
[similarity.suggestions]
A review queue of texts the text rules found to be spam (/v2/training-suggestions). Stores message text.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | false | Collect suggestions. |
retention | duration | "7d" | Queued suggestions older than this are deleted (1h–90d). |
max_per_account | integer | 1000 | Soft cap per account and replica; new texts are dropped when full. |
See Similarity.