Configuration

The KronosDB server settings an operator sets, with their config file key, command-line flag, environment variable and default.

The kronosdb-server binary reads its settings from command-line flags, environment variables and an optional TOML file. This page lists the settings, grouped by area. The container image runs the binary as its entrypoint, so anything after the image name in docker run is a flag, and -e sets an environment variable.

Sources and precedence

A setting resolves from the first source that provides it, in this order: command-line flag, environment variable, config file, default. A flag and its environment variable are the same setting, so --listen 0.0.0.0:50051 and KRONOSDB_LISTEN=0.0.0.0:50051 are equivalent.

The config file is TOML. --config (short form -c, environment variable KRONOSDB_CONFIG) names it. Without that setting the server reads kronosdb.toml in its working directory when the file exists. A file that cannot be parsed stops the server at startup. Unrecognized keys are ignored outside the [[security.tokens]], [[security.issuers]] and [[security.grants]] entries, so a misspelled key leaves the default in place.

# kronosdb.toml
listen = "0.0.0.0:50051"
data-dir = "/data"
node-name = "kronosdb-0"

[storage]
ack-mode = "auto"

[admin]
listen = "0.0.0.0:9240"

[admin.auth]
mode = "token"
token = "change-me"

none in a table means the setting has no form in that source. Sizes are bytes and durations are whole seconds unless the Meaning column gives another unit.

Server

Config file keyFlagEnvironment variableDefaultMeaning
none--config, -cKRONOSDB_CONFIGkronosdb.toml if presentPath of the config file.
data-dir--data-dirKRONOSDB_DATA_DIRdata (/data in the image)Directory that holds every context. The server takes an exclusive lock on <data-dir>/LOCK and does not start when another process holds it.
node-name--node-nameKRONOSDB_NODE_NAMEkronosdb-0Name this node reports to clients and in the console.
manifest--manifestKRONOSDB_MANIFESTkronosdb-manifest.toml in the working directory, if presentPath of the manifest that declares contexts.
dev--devKRONOSDB_DEVfalseLogs the startup hardware findings at info instead of warn or error. Accepts true, false, 1, 0, yes, no, on, off; an empty value means off. Never set it on a production node.
none--drain-deadline-secsKRONOSDB_DRAIN_DEADLINE20Seconds the server waits for open connections to close after SIGTERM before it exits.

Network

Config file keyFlagEnvironment variableDefaultMeaning
listen--listenKRONOSDB_LISTEN127.0.0.1:50051 (0.0.0.0:50051 in the image)Address of the client and peer port. Clients, other nodes and the kronos CLI all connect here.
[admin] listen--admin-listenKRONOSDB_ADMIN_LISTEN127.0.0.1:9240 (0.0.0.0:9240 in the image)Address of the admin HTTP port: console, JSON API, /health, /ready and /metrics. It has no TLS of its own.

TLS for the client port is configured under Auth. A single request is limited to 16 MiB, and the server has no setting for it.

Storage

Config file keyFlagEnvironment variableDefaultMeaning
[storage] segment-size--segment-sizeKRONOSDB_SEGMENT_SIZE268435456 (256 MiB)Size at which a context rolls to a new segment file.
[storage] index-cache-bytes--index-cache-bytesKRONOSDB_INDEX_CACHE_BYTES1073741824 (1 GiB)Heap budget for cached segment indexes.
[storage] bloom-cache-bytes--bloom-cache-bytesKRONOSDB_BLOOM_CACHE_BYTES134217728 (128 MiB)Heap budget for cached bloom filters.
[storage] max-snapshot-size--max-snapshot-sizeKRONOSDB_MAX_SNAPSHOT_SIZE4194304 (4 MiB)Largest snapshot state a client may store. Snapshot records share the log with events, and a larger blob is rejected.

The index and bloom budgets together should stay well under half of the memory the node has, because reads use the operating system's page cache. The startup hardware check reports a low_memory finding when they exceed half.

Durability

Config file keyFlagEnvironment variableDefaultMeaning
[storage] ack-mode--ack-modeKRONOSDB_ACK_MODEautoWhen an append is acknowledged. durable waits until a quorum has fsynced. written waits until a quorum has written the events, and the fsync trails by one group-commit wave. auto is durable on a single voter, and on two or more voters is durable when the startup disk probe measures an fdatasync p99 under 1 ms and written otherwise. An empty environment variable counts as unset.
none--group-commit-msKRONOSDB_GROUP_COMMIT_MS0Extra milliseconds the writer waits to batch commits. At 0 it fsyncs as soon as writes are pending, and concurrent writes batch while the fsync runs. A positive value adds that much latency for larger batches.
nonenoneKRONOSDB_ACK_LAG_LIMIT65536Under written acknowledgements, how many events may be acknowledged ahead of the locally fsynced position. Past it, appends wait for the fsync as in durable mode.

Cluster

Run a cluster describes how these fit together. They are set with flags or environment variables, and have no config file key.

Config file keyFlagEnvironment variableDefaultMeaning
none--cluster-node-idKRONOSDB_CLUSTER_NODE_IDunset (treated as 1)Numeric id of this node. It must be unique in the cluster and stay the same across restarts.
none--cluster-peersKRONOSDB_CLUSTER_PEERSemptyComma-separated id=address entries for every voter, this node included, for example 1=node1:50051,2=node2:50051,3=node3:50051. Empty means a single-node cluster. Use stable host names, because the addresses are stored in the cluster's membership.
none--cluster-learnersKRONOSDB_CLUSTER_LEARNERSemptyComma-separated id=address entries for passive-backup learners the node adds to the membership at startup.
none--cluster-node-typeKRONOSDB_CLUSTER_NODE_TYPEstandardstandard for a voter, or passive-backup for a learner that replicates everything and never votes.

Auth

These settings protect the client and peer port. Secure a server explains how they combine. Nothing here is set by default, and the port is open until at least one credential is configured.

Config file keyFlagEnvironment variableDefaultMeaning
[security] access-token--access-tokenKRONOSDB_ACCESS_TOKENunsetShared secret that grants full access, including the peer role. Setting it makes every client present a credential. Nodes use it to authenticate to each other.
[security] tls-cert--tls-certKRONOSDB_TLS_CERTunsetServer certificate chain, PEM. Also the identity this node presents to its peers.
[security] tls-key--tls-keyKRONOSDB_TLS_KEYunsetPrivate key of the certificate, PEM. Both tls-cert and tls-key are needed for TLS.
[security] tls-ca--tls-caKRONOSDB_TLS_CAunsetCA certificate, PEM. Client certificates are verified against it, and a node uses it to verify its peers.
[security] tls-client-auth--tls-client-authKRONOSDB_TLS_CLIENT_AUTHrequiredWith tls-ca set, required rejects connections that present no certificate. optional verifies a certificate when one is presented and lets token callers connect without one. optional fails to start unless some authentication is configured.

The three list tables below have no flag or environment form and are read from the config file only.

[[security.tokens]] declares a named static token.

KeyDefaultMeaning
namerequiredName shown in the access summary and logs.
tokenunsetThe secret. Exactly one of token and token-file is required.
token-fileunsetFile that holds the secret, such as a mounted Kubernetes secret.
rolesrequiredOne or more of read, write, admin, peer.
contextsallContext name patterns the token is limited to. * matches any run of characters.
busesallBus name patterns the token is limited to.

[[security.issuers]] declares an OpenID Connect issuer whose JWTs the server trusts.

KeyDefaultMeaning
namerequiredName that a grant's source uses. mtls is reserved.
issuerrequiredMust equal the token's iss claim exactly.
audiencesemptyAccepted aud values. Empty means the audience is not checked.
jwks-uridiscoveredFetch the signing keys from this URL instead of using OIDC discovery. Not combinable with jwks-file.
jwks-fileunsetRead the signing keys from a local file, re-read on the normal refresh interval.
ca-fileunsetExtra root CA, PEM, for the discovery and key fetch.
jwks-bearer-token-fileunsetFile with a bearer token sent when fetching the keys.
subject-claimsubClaim that names the caller.
role-claimunsetDotted path to a roles claim, such as realm_access.roles.
role-mapemptyTable that maps an identity provider role name to a KronosDB role. Roles granted this way apply to every context and bus.

[[security.grants]] binds callers from one source to roles.

KeyDefaultMeaning
sourcerequiredAn issuer name, or mtls for client certificates.
subject*Pattern over the caller's subject. For mtls the server tries each URI SAN, then each DNS SAN, then the CN.
claimsemptyClaims a JWT must carry, as a table. A scalar must be equal, and an array claim matches when it contains the value. Not allowed for mtls.
rolesrequiredRoles the grant confers.
contextsallContext name patterns. A grant limited to contexts never confers admin or peer.
busesallBus name patterns.

Admin

The admin port is configured separately from the client port. The default mode is none.

Config file keyFlagEnvironment variableDefaultMeaning
[admin.auth] mode--admin-auth-modeKRONOSDB_ADMIN_AUTH_MODEnonenone, token or oidc.
[admin.auth] token--admin-tokenKRONOSDB_ADMIN_TOKENunsetStatic bearer token. Required when the mode is token.
[admin.oidc] issuer--oidc-issuerKRONOSDB_OIDC_ISSUERunsetIssuer URL of the identity provider. Required when the mode is oidc.
[admin.oidc] client-id--oidc-client-idKRONOSDB_OIDC_CLIENT_IDunsetOAuth client id. Required when the mode is oidc.
[admin.oidc] client-secret--oidc-client-secretKRONOSDB_OIDC_CLIENT_SECRETunsetOAuth client secret. Omit it for a public client; PKCE is always used.
[admin.oidc] redirect-url--oidc-redirect-urlKRONOSDB_OIDC_REDIRECT_URLderived from the requestCallback URL registered at the provider, ending in /auth/callback. When unset the server builds it from the Host and X-Forwarded-Proto headers.
[admin.oidc] scopesnonenone["openid", "profile", "email"]Scopes requested at login.
[admin.oidc] role-claim--oidc-role-claimKRONOSDB_OIDC_ROLE_CLAIMunsetDotted path to the roles claim, such as realm_access.roles.
[admin.oidc] required-role--oidc-required-roleKRONOSDB_OIDC_REQUIRED_ROLEunsetRole a user must have. Unset lets any authenticated user of the realm in.
[admin.oidc] audience--oidc-audienceKRONOSDB_OIDC_AUDIENCEunsetExpected aud of bearer tokens. Unset means it is not checked.
[admin.oidc] cookie-secret--oidc-cookie-secretKRONOSDB_OIDC_COOKIE_SECRETrandom per startKey that signs session cookies. Set it so sessions survive restarts and work across replicas.
[admin.oidc] session-ttl-minutesnonenone480Lifetime of a console session.

Backup

Config file keyFlagEnvironment variableDefaultMeaning
[backup] url--backup-urlKRONOSDB_BACKUP_URLunsetObject store that receives sealed segments, such as s3://bucket/prefix or file:///backups/kronosdb. Unset turns the upload off. Cloud credentials come from the standard environment variables of the provider.
[backup] interval-secs--backup-interval-secsKRONOSDB_BACKUP_INTERVAL_SECS30Seconds between upload passes on the leader.

What the upload does and does not give you is described in Back up and restore.

Limits and timeouts

Config file keyFlagEnvironment variableDefaultMeaning
[timeouts] command--command-timeoutKRONOSDB_COMMAND_TIMEOUT30Seconds a dispatched command may take. The server also cancels an in-flight command that has not completed after twice this value.
[timeouts] query--query-timeoutKRONOSDB_QUERY_TIMEOUT30Seconds a dispatched query may take.
[timeouts] heartbeat-interval--heartbeat-intervalKRONOSDB_HEARTBEAT_INTERVAL5Seconds between the heartbeats the server sends on each client's platform stream.
[timeouts] heartbeat-timeout--heartbeat-timeoutKRONOSDB_HEARTBEAT_TIMEOUT15Seconds without a heartbeat after which a client is dropped from its buses and the routing table.
[messaging] permit-waitnonenonetrueWhen a command handler has no flow-control permits left, wait for one, bounded by the command timeout. false fails the command at once.

max-snapshot-size is the other limit; it appears under Storage.

Logging

Logging is configured through the environment only.

Environment variableDefaultMeaning
RUST_LOGkronosdb=info,warnLog filter in the tracing format: a level, or a comma-separated list of target=level. The default logs KronosDB at info and everything else at warn.
KRONOSDB_LOG_FORMATtextjson writes one JSON object per line. Any other value keeps the text format.

On this page