Server settings¶
Every setting is an environment variable. An empty value means unset for all of them except SNODRA_SERVER_OTLP_ENDPOINT, where an empty value disables export. Durations accept 30, 30s, 500ms and 5m.
Identity and listeners¶
| Variable | Default | Meaning |
|---|---|---|
SNODRA_SERVER_ID |
hostname + - + 8 random hex digits |
identifies this hub process in RegisterAck.hub_id and the topology (hubId) |
SNODRA_SERVER_LISTEN |
0.0.0.0:7000 |
gRPC bind address |
SNODRA_SERVER_HTTP_LISTEN |
0.0.0.0:7001 |
HTTP bind address for the dashboard and its API; empty disables the HTTP listener |
SNODRA_SERVER_OTLP_ENDPOINT |
http://otel-lgtm:4317 |
OTLP gRPC endpoint for traces and metrics |
SNODRA_SERVER_LOG |
info |
tracing filter, for example snodra_hub=debug,info |
SNODRA_SERVER_JWKS_REFRESH |
5m |
how often the signing keys are fetched again (an unknown kid fetches at most once per 30 s on top); positive |
Timeouts¶
| Variable | Default | Meaning |
|---|---|---|
SNODRA_SERVER_DEFAULT_TIMEOUT_MS |
5000 |
used when Request.timeout_ms is 0 and the type has no override |
SNODRA_SERVER_MAX_TIMEOUT_MS |
60000 |
upper clamp for Request.timeout_ms on types without an override |
SNODRA_SERVER_TIMEOUT_OVERRIDES |
none | per-type timeouts, type=ms,type=ms (for example files.Upload=120000); see Request timeouts |
SNODRA_SERVER_HEARTBEAT_TIMEOUT |
10s |
dead-instance threshold (10, 10s or 500ms) |
SNODRA_SERVER_MAX_STREAM_DURATION |
10m |
a streaming query open for longer ends with ReplyEnd{error = CANCELLED} and its handler is cancelled; at least 1s |
SNODRA_SERVER_MAX_SUBSCRIPTION_DURATION |
0 |
a subscription open for longer ends with ReplyEnd{error = CANCELLED} and its targets are cancelled; 0 is unlimited, otherwise at least 1s |
SNODRA_SERVER_HANDSHAKE_TIMEOUT |
10s |
a new Connect stream must send Register within this (10, 10s or 500ms) |
Heartbeats, sessions and flow control¶
| Variable | Default | Meaning |
|---|---|---|
SNODRA_SERVER_HEARTBEAT_INTERVAL |
3s |
heartbeat period announced to clients in RegisterAck; SNODRA_SERVER_HEARTBEAT_TIMEOUT must be at least twice it |
SNODRA_SERVER_QUEUE_CAPACITY_PER_INSTANCE |
10000 |
requests queued for one instance before new ones are rejected |
SNODRA_SERVER_QUEUE_BYTES_PER_INSTANCE |
64MiB |
encoded bytes queued for one instance before new requests are rejected (B, KiB, MiB, GiB, or plain bytes) |
SNODRA_SERVER_QUEUE_BYTES_TOTAL |
512MiB |
encoded bytes queued over all instances together before new requests are rejected (reason queue_bytes_total; same units) |
SNODRA_SERVER_OWNER_GRACE |
60s |
keep type ownership after the last instance leaves |
SNODRA_SERVER_SUBSCRIPTION_BUFFER |
256 |
updates of a subscription the hub holds while its sender owes credit; one more ends it with ReplyEnd{error = RESOURCE_EXHAUSTED}; positive |
SNODRA_SERVER_MAX_SUBSCRIPTIONS_PER_INSTANCE |
1024 |
subscription targets one handler instance serves at once; a subscription that would exceed it on any target is refused with Error{RESOURCE_EXHAUSTED} before anything is sent; positive |
SNODRA_SERVER_SESSION_BUFFER |
1024 |
per-session outbound buffer, in messages |
Dashboard and topology¶
| Variable | Default | Meaning |
|---|---|---|
SNODRA_SERVER_DASHBOARD_ENABLED |
true |
serve the dashboard (/ui/) and its API (/api/v1/, the processor controls included) on the HTTP port and keep the edge statistics; false makes them 404 (true/false, 1/0, yes/no, on/off) |
SNODRA_SERVER_GRAFANA_URL |
none | Grafana base URL the dashboard links to; must be http:// or https:// without user info (user:password@ is rejected at startup, as the link is served unauthenticated) |
SNODRA_SERVER_EDGE_STATS_MAX_EDGES |
10000 |
cap on (sender service, type) edges kept for the dashboard graph; at the cap the least recently used go first |
SNODRA_SERVER_EDGE_STATS_WINDOW |
5m |
sliding window of the edge statistics, at least 10s |
SNODRA_SERVER_PEERS |
none | the other hubs' dashboard base URLs as the operator's browser reaches them, comma-separated, for example http://localhost:7001,http://localhost:7011 (this hub's own URL may be listed; the page skips it by hub id). Each must be http:// or https:// with a host and optional port, no user info, no path beyond /; normalised to origins (lowercase, default port dropped), duplicates removed, at most 16; anything else stops the hub at startup. See Multiple hubs |
Processor control¶
| Variable | Default | Meaning |
|---|---|---|
SNODRA_SERVER_CONTROL_TIMEOUT |
10s |
how long a control call waits for an instance's answer (pause, resume, a reset's prepare and finish, dead letters) |
SNODRA_SERVER_RESET_TIMEOUT |
120s |
how long the instance that executes a reset may take |
Authentication, TLS and tokens¶
| Variable | Default | Meaning |
|---|---|---|
SNODRA_SERVER_AUTH_MODE |
off |
off, permissive (evaluate every rule, log and count violations, allow everything) or enforce (refuse them); anything but off needs SNODRA_SERVER_ACL_FILE. See Security |
SNODRA_SERVER_ACL_FILE |
none | TOML ACL: SHA-256 of each static token to its service, handle and send patterns; reloaded when it changes |
SNODRA_SERVER_JWT_ISSUER |
none | the iss a JWT credential must carry, exact match; unset: JWT credentials are off and refused as "not configured". Needs an auth mode other than off. See Security |
SNODRA_SERVER_JWT_JWKS_URI |
<issuer>/protocol/openid-connect/certs |
where the signing keys are fetched from (the default OpenID Connect path; there is no discovery); separate from the issuer so a hub can fetch internally and validate the public issuer. http:// warns once unless loopback or a single-label name. Without an issuer it is a startup error |
SNODRA_SERVER_JWT_AUDIENCE |
none | when set, a JWT's aud (string or array) must contain it |
SNODRA_SERVER_JWT_LEEWAY |
30s |
clock skew tolerated on exp, nbf and iat |
SNODRA_SERVER_JWT_EXPIRY_GRACE |
30s |
how long after exp a JWT session stays open without a refresh |
SNODRA_SERVER_JWT_JWKS_CA |
none | an extra CA (PEM) trusted for the key fetch, on top of the platform roots; an unreadable file is a startup error whatever the URI scheme (unused, with a warning, over http://) |
SNODRA_SERVER_RELOAD_INTERVAL |
5s |
how often the ACL and the TLS pairs are checked for changes; SIGHUP reloads at once |
SNODRA_SERVER_TLS_CERT, SNODRA_SERVER_TLS_KEY |
none | PEM pair of the gRPC listener, both or neither; the listener then accepts TLS only |
SNODRA_SERVER_TLS_CLIENT_CA |
none | PEM bundle of the CAs whose client certificates the gRPC listener accepts (mutual TLS); needs the gRPC pair; an unreadable or empty bundle is a startup error; reloaded with the certificates (a bad file keeps the previous CAs, counted); the HTTP port never asks for a certificate; with AUTH_MODE=off it authenticates nothing beyond the handshake (startup warning). See Security |
SNODRA_SERVER_TLS_CLIENT_AUTH |
optional (when the CA is set) |
optional: no certificate is fine (token or JWT), one that is presented must verify; required: a client without a valid certificate fails the handshake. Without SNODRA_SERVER_TLS_CLIENT_CA it is a startup error |
SNODRA_SERVER_HTTP_TLS_CERT, SNODRA_SERVER_HTTP_TLS_KEY |
the gRPC pair | PEM pair of the HTTP listener |
SNODRA_SERVER_TLS_HANDSHAKE_TIMEOUT |
5s |
a TLS handshake that takes longer is dropped; positive |
SNODRA_SERVER_TLS_HANDSHAKES_PER_IP |
32 |
TLS handshakes in progress at once from one peer IP; more are dropped at once; 0 removes the cap |
SNODRA_SERVER_DASHBOARD_TOKEN |
none | at least 16 characters; when set /api/v1/* and the gRPC Topology call need Authorization: Bearer <token> |
SNODRA_SERVER_DASHBOARD_TOKEN_FILE |
none | a file holding the dashboard token (trailing newline trimmed, same rules as the variable); read at startup and again on the reload poll, so a rotation needs no restart. Wins over SNODRA_SERVER_DASHBOARD_TOKEN when both are set (as SNODRA_MESSAGING_HUB_TOKEN_FILE does in the client libraries). An unreadable or invalid file stops the hub at startup; at a reload it keeps the previous token and logs an error. Prefer it to the variable: an environment variable shows in docker inspect and /proc |
SNODRA_SERVER_DASHBOARD_WRITE_TOKEN, SNODRA_SERVER_DASHBOARD_WRITE_TOKEN_FILE |
none | at least 16 characters; the processor controls' token (Authorization: Bearer <token> on the mutating calls), which also reads what the dashboard token reads; the file variant is read and reloaded like SNODRA_SERVER_DASHBOARD_TOKEN_FILE. Equal to the dashboard token (whatever the source) is a config error at start, and a reload that would make them equal keeps both previous tokens. Unset and no ACL entry with control = true: the controls answer 403 controls are disabled |
Event browser¶
| Variable | Default | Meaning |
|---|---|---|
SNODRA_SERVER_KAFKA_BOOTSTRAP |
none | Kafka bootstrap servers the event browser reads (plaintext); unset: the event browser and the consumer groups are off (404) and their pages hidden |
SNODRA_SERVER_EVENT_TOPICS |
snodra.events |
the only topics the event browser and its tail read, comma-separated, the first the default; a <topic>.dlt is browsable when listed |
SNODRA_SERVER_EVENT_BROWSER_PAYLOADS |
false |
serve event payloads (record detail, q) to a request that presents the dashboard or write token (a token must be configured too) |
SNODRA_SERVER_EVENT_SEARCH_MAX_SCANNED |
50000 |
records one search reads from Kafka at most |
SNODRA_SERVER_EVENT_SEARCH_MAX_RESULTS |
100 |
results one search page returns at most (1 to 1000) |
SNODRA_SERVER_EVENT_SEARCH_TIMEOUT |
10s |
time budget of one search, record read or consumer-group listing, Kafka calls included |
SNODRA_SERVER_EVENT_MAX_SEARCHES |
4 |
searches, record reads and group listings at once; one more is 429 |
SNODRA_SERVER_EVENT_MAX_TAILS |
4 |
event tails at once; one more is 429 |
SNODRA_SERVER_EVENT_TAIL_DURATION |
15m |
a tail ends (maxDuration) after this long; at least 1s |
SNODRA_SERVER_GROUP_LAG_INTERVAL |
60s |
How often the consumer-group lag task reads every group on the event topics; 0 turns it off |
Startup checks¶
Startup fails on a malformed SNODRA_SERVER_TIMEOUT_OVERRIDES, when SNODRA_SERVER_HEARTBEAT_TIMEOUT is less than twice SNODRA_SERVER_HEARTBEAT_INTERVAL, on a malformed ACL file, on an unreadable TLS pair, and on a dashboard token shorter than 16 characters.
On macOS, port 7000 is used by Control Center (AirPlay Receiver); set SNODRA_SERVER_LISTEN=0.0.0.0:7002 or disable it.