The configuration file
Sentinel reads all server settings from one TOML file. Changes take effect after a restart, and unknown keys stop the server from starting. Tenant settings, such as accounts and security groups, are managed at runtime instead; see Accounts & policies.
Server settings and tenant settings
Sentinel has two places to configure, owned by different people:
| Server settings | Tenant settings | |
|---|---|---|
| What | Listeners, database, KV store, secrets, license, sign-in methods, remote lists, alerts delivery, storage, telemetry | Accounts, users, roles, API keys, security groups and their rules, training data, threat entries |
| Where | sentinel.toml | Admin UI or the /v2 API |
| Who | The operator who runs Sentinel | Root users and account admins |
| When it applies | At the next restart | Immediately, on every replica |
This section covers server settings. Every key, its type, and its default are listed in the Configuration reference.
Where the file is loaded from
Sentinel looks for its configuration in this order:
- The path given with
--config(or-c). If that file can't be read, startup fails. - Otherwise,
sentinel.tomlin the working directory, if it exists. - Otherwise, Sentinel starts with the built-in defaults for every key.
Sentinel ships as the container image ghcr.io/altcha-org/sentinel, whose entrypoint is the altcha-sentinel binary, so arguments after the image name go to it. To keep the file outside the working directory, mount it anywhere and pass the path:
docker run -d --name sentinel -p 3000:3000 \
-v "$PWD/sentinel.toml:/etc/sentinel/sentinel.toml:ro" \
-v "$PWD/secrets:/run/secrets:ro" \
ghcr.io/altcha-org/sentinel:2.0.0-beta.1 --config /etc/sentinel/sentinel.tomlEvery key is optional, so the file only needs the settings you change. The same --config flag applies to the CLI commands that read the configuration (doctor, healthcheck, license request, migrate, schema sql); see the CLI reference.
Environment variables and secret files
Any string value can contain ${…} references. Sentinel expands them once at startup, after parsing the TOML:
| Syntax | Expands to |
|---|---|
"${VAR}" | The value of environment variable VAR. An unset or empty variable expands to an empty string. |
"${VAR:-fallback}" | The value of VAR, or fallback when VAR is unset or empty. |
"${file:/path}" | The contents of the file at /path, with one trailing newline (\n or \r\n) removed. A missing file stops startup. |
"${file:/path:-fallback}" | The file contents, or fallback when the file is missing or empty. |
'\${VAR}' | The literal text ${VAR}, not expanded. |
A few rules follow from how expansion works:
- Empty means unset. A string that is empty, literally or after expansion, is removed before the configuration is checked, so the key takes its default.
jwt_secret = "${JWT_SECRET}"withJWT_SECRETunset behaves as if the key were missing. - Only strings are expanded. Numbers and booleans are literal.
port = "${PORT:-3000}"is a string, and Sentinel rejects it withinvalid type: string "3000", expected u16. - References can sit inside a value, for example a password inside a connection string:
url = "postgres://app:${DB_PASSWORD}@db:5432/sentinel". - Variable names must look like
[A-Za-z_][A-Za-z0-9_]*. Anything else, such as${JWT-SECRET}, stops startup withinvalid variable name. There is no nesting: the first}closes the reference. - Escaping. The backslash must reach Sentinel, so use a single-quoted TOML string (
'\${VAR}') or escape it in a double-quoted one ("\\${VAR}").
This example reads the root password from the environment with a fallback, and the challenge secret from a mounted file:
[bootstrap]
root_password = "${ROOT_PASSWORD:-change-me-on-first-login}"
[secrets]
altcha_hmac_secret = "${file:/run/secrets/altcha_hmac_secret}"
jwt_secret = "${JWT_SECRET}"If a reference can't be resolved, the error names the key but never prints its value:
Error: loading config sentinel.toml
Caused by:
0: config key `secrets.altcha_hmac_secret`
1: config: reading secret file '/run/secrets/altcha_hmac_secret': No such file or directory (os error 2)Keep every secret in an environment variable or a file, never as a literal in sentinel.toml. Which values are secrets, and what rotating them breaks, is covered in Server secrets.
Unknown keys and invalid values stop startup
Sentinel rejects any key it doesn't recognize, in every section. A typo fails loudly instead of being silently ignored. For example, prot = 3000 under [server]:
Error: loading config sentinel.toml
Caused by:
unknown field `prot`, expected one of `host`, `port`, `trusted_proxies`, `client_ip_header`, `forwarded_host_header`, `base_url`, `v1_compat`, `public_api`, `admin_ui`
in `server`After loading, Sentinel also checks values and combinations of keys (ranges, required companions, mutually exclusive keys) before it opens any connection. The process exits with code 1 and the reason on stderr.
TOML syntax errors report the line and column but not the source line, because it might contain a secret.
Changes need a restart
Sentinel reads the file only at startup. There is no hot reload: edit the file, then restart the process (or roll your replicas). The same applies to files the configuration points to, such as tls certificates: a renewed certificate takes effect at the next restart. In a cluster, give every replica the same file; see Clustering & high availability.
Validate the file
Run doctor --config-only to check a file without starting the server. It loads and expands the file and runs the same checks as startup, but opens no connections, so it suits CI and pre-deploy hooks. Run it in a one-off container with the same mounts as the server:
docker run --rm \
-v "$PWD/sentinel.toml:/etc/sentinel/sentinel.toml:ro" \
-v "$PWD/secrets:/run/secrets:ro" \
ghcr.io/altcha-org/sentinel:2.0.0-beta.1 --config /etc/sentinel/sentinel.toml doctor --config-onlyaltcha-sentinel 2.0.0-beta.1 doctor, config: /etc/sentinel/sentinel.toml
config
ok config.file Loaded /etc/sentinel/sentinel.toml.
ok config.valid The configuration passes the startup checks.
2 ok, 0 warn, 0 fail, 0 skipped in 2 msA failing check prints FAIL with the error and a hint, and the command exits with 1:
config
ok config.file Loaded sentinel.toml.
FAIL config.valid (license) [license] file and key are mutually exclusive.
hint: Fix this setting; the server does not start with it.Run the check with the same environment variables (-e or --env-file) and mounted files as the server, because ${…} references are expanded and the tls certificate files of enabled listeners are loaded during validation. Without --config-only, doctor also checks storage, network access, and the rest of the host, so run the full check inside the running container (docker exec sentinel /usr/local/bin/altcha-sentinel --config /etc/sentinel/sentinel.toml doctor); see Troubleshooting and the CLI reference.
The data directory
data_dir (default ./data, relative to the working directory) holds local state. Sentinel creates it at startup when it uses the embedded SQLite database. A single node with default settings ends up with:
data/
├── sentinel.db # embedded SQLite database (plus -wal and -shm files in WAL mode)
├── secrets.json # generated secrets, only when some [secrets] keys are unset
├── remote-files/ # downloaded lists and their .meta.json state
├── threats/ # one SQLite index per threat source
└── eml/ # index of malicious attachment hashessentinel.dbexists only while[database] urlis unset. With an external database, nothing is stored there.secrets.jsonis written only with embedded SQLite, for the secrets you didn't set. Back it up: losing it invalidates sessions, challenges, and stored encrypted values. See Server secrets.remote-files/,threats/, andeml/are caches that Sentinel rebuilds from their sources. See Remote files & data sources.- Relative paths of local MaxMind or IPinfo databases in
[[ip_resolver.providers]]resolve insidedata_dir. See IP resolvers.
Mount data_dir on a persistent volume. If that volume is network storage (AWS EFS, NFS, or an SMB share such as Azure Files), set [database] sqlite_journal_mode = "delete"; see SQLite on network storage. See Top level in the reference.
A production starting point
This file runs one replica with PostgreSQL and Redis, the admin UI behind a TLS proxy, and every secret read from a mounted file. Adjust the hosts and paths, then add the sections you need. Without a proxy, set tls on each listener you expose instead; see Listener TLS.
data_dir = "/home/nonroot/data"
[server]
host = "0.0.0.0"
port = 3000
base_url = "https://sentinel.example.com"
trusted_proxies = ["10.0.0.0/8"] # your reverse proxy or load balancer
[server.admin_ui]
enabled = true
host = "0.0.0.0" # default 127.0.0.1; expose only behind HTTPS
base_url = "https://admin.sentinel.example.com"
[database]
url = "postgres://sentinel:${file:/run/secrets/db_password}@db:5432/sentinel"
[redis]
nodes = ["redis://:${file:/run/secrets/redis_password}@redis:6379"]
[secrets]
jwt_secret = "${file:/run/secrets/jwt_secret}"
altcha_hmac_secret = "${file:/run/secrets/altcha_hmac_secret}"
encryption_key = "${file:/run/secrets/encryption_key}"
[license]
key = "${file:/run/secrets/sentinel_license_key}"
[bootstrap]
root_password = "${file:/run/secrets/root_password}"What each section does and where to read more:
| Section | Read more |
|---|---|
[server], [server.admin_ui] | Listeners & reverse proxy, reference [server] and [server.admin_ui] |
[database], [redis] | Databases & KV store, reference [database] and [redis] |
[secrets], [bootstrap] | Server secrets, reference [secrets] and [bootstrap] |
[license] | Configure the license, reference [license] |
What a production deployment needs beyond this file (replica count, backups, sizing) is listed in Install. Before going live, work through the Production checklist.
In this section
- Configure the license: Install an offline license file or an online license key, check the license status, and understand instance slots.
- Listeners & reverse proxy: Configure Sentinel's main, public widget, admin UI, and Prometheus listeners, its base URL, trusted proxies, and client IP headers.
- Databases & KV store: Choose and configure Sentinel's database (SQLite, PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, or remote ExotDB) and its KV store.
- Server secrets: Set the JWT, HMAC, encryption, and VAPID secrets and the bootstrap root password, and understand what rotating them breaks.
- IP resolvers: Configure the providers Sentinel uses to add location and network data to client IP addresses.
- Object storage: Configure S3-compatible or Azure Blob storage for email attachment uploads and stored snapshots.
- Remote files & data sources: Which lists and databases Sentinel downloads, where they come from, how often they refresh, and how to manage them.
- Outbound proxy & air-gapped deployments: Run Sentinel behind an outbound HTTP proxy or with no internet access: required hosts, mirrored lists, and offline licensing.