# Configuration reference

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

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](/docs/sentinel/v2/configure/).

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

## [server]

The main API listener, serving every `/v2` route, the `GET /` liveness probe, and the [`GET /.health`](#health-endpoint) 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](#allowed-hosts). Empty: any host. |
| `health_allowed_ips` | string[] | private networks | CIDRs or IPs of clients allowed [`GET /.health`](#health-endpoint), 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](#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](#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](/docs/sentinel/v2/configure/listeners/).

### 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.

```toml
[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`](/docs/sentinel/v2/reference/cli/#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.

```json
{"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]`](#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.

```toml
[server]
health_allowed_ips = ["10.0.0.0/8", "35.191.0.0/16", "130.211.0.0/22"]
```

<Callout type="warning" title="Not a liveness or readiness probe">
Every replica shares the same storage, so an outage turns every replica's `/.health` to `503` at once. A readiness probe would take all replicas out of service, and a liveness probe would restart them without fixing anything, although some requests keep working through an outage (a KV outage fails open). Probe `GET /` and use `/.health` for monitoring and alerting.

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

```toml
[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`](/docs/sentinel/v2/reference/cli/) 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](#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](#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](#listener-tls). |

See [Listeners & reverse proxy](/docs/sentinel/v2/configure/listeners/).

## [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](#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](#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](#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](/docs/sentinel/v2/configure/listeners/).

## [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](/docs/sentinel/v2/operations/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](#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](/docs/sentinel/v2/configure/databases/#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](/docs/sentinel/v2/operations/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](/docs/sentinel/v2/configure/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`](#top-level) 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](#oracle-tls) | Plain TCP unless the connect string uses `tcps` |

```toml
[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`](#top-level) 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:

```toml
[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`:

```bash
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`.

```bash
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:

```yaml
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
```

```toml
[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`.

```text
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`](#top-level), 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]`](#redissentinel). 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`](#rate_limit). `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](/docs/sentinel/v2/operations/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`](#redis) (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`](#rate_limit).

```toml
[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. |

```toml
[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](/docs/sentinel/v2/configure/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](/docs/sentinel/v2/operations/clustering/#standby-instances): 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](/docs/sentinel/v2/configure/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](/docs/sentinel/v2/features/threat-intelligence/#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]`](#authldap). |

See [Sign-in](/docs/sentinel/v2/security/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](/docs/sentinel/v2/security/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](/docs/sentinel/v2/security/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](/docs/sentinel/v2/security/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](/docs/sentinel/v2/security/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`](#top-level), 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](/docs/sentinel/v2/security/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`](#redis), before switching to the fallback. |

See [Rate limiting](/docs/sentinel/v2/features/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](/docs/sentinel/v2/features/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](/docs/sentinel/v2/integrate/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](/docs/sentinel/v2/policies/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](/docs/sentinel/v2/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](/docs/sentinel/v2/security/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](/docs/sentinel/v2/operations/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](/docs/sentinel/v2/operations/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]]`](#alertswebhooks). |

See [Alerts](/docs/sentinel/v2/operations/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](/docs/sentinel/v2/operations/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](/docs/sentinel/v2/operations/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](/docs/sentinel/v2/operations/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]]`](#ip_resolverproviders) 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]`](#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]`](#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](/docs/sentinel/v2/operations/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`](#top-level), 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](/docs/sentinel/v2/operations/schema-migrations/#clickhouse). |

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](/docs/sentinel/v2/operations/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](/docs/sentinel/v2/configure/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](/docs/sentinel/v2/configure/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](/docs/sentinel/v2/operations/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]`](#threatssignals). |

See [Threat intelligence](/docs/sentinel/v2/features/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](/docs/sentinel/v2/features/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](#classifier-lists). |
| `ai` | table | — | AI decider; see [`[classifier.ai]`](#classifierai). |

See [Classifier](/docs/sentinel/v2/features/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](/docs/sentinel/v2/configure/remote-files/) and [Classifier rules](/docs/sentinel/v2/reference/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](/docs/sentinel/v2/features/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]`](#emlmalicious_hashes). |

See [Email analysis](/docs/sentinel/v2/features/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](/docs/sentinel/v2/features/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]`](#storages3). |
| `azure` | table | — | See [`[storage.azure]`](#storageazure). |

See [Object storage](/docs/sentinel/v2/configure/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](/docs/sentinel/v2/configure/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](/docs/sentinel/v2/operations/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](/docs/sentinel/v2/features/bots-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](/docs/sentinel/v2/features/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](#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](#allowed-hosts). Scrapers usually address the IP, so list it. |
| `tls` | table | — | Serve metrics over HTTPS; see [Listener TLS](#listener-tls). |

See [Monitoring](/docs/sentinel/v2/operations/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](/docs/sentinel/v2/operations/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`). |

See [Air-gapped deployments](/docs/sentinel/v2/configure/air-gapped/).

## [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](/docs/sentinel/v2/operations/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](/docs/sentinel/v2/features/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](/docs/sentinel/v2/features/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](/docs/sentinel/v2/features/similarity/).
