Server Configuration
This page is the reference for every kahuna-server command-line flag currently exposed by KahunaCommandLineOptions. Feature pages explain when to use a setting and link here for the full flag list.
Most sections are a table of flags, descriptions, and defaults. Sections are grouped by area: network, security, and health surfaces first; then storage, cluster identity, and replica placement; then workers, key/value, range, backup, and retention settings; then the Raft groups; and finally general configuration notes.
Most options have safe defaults, and a typical deployment sets only a few groups:
- Node identity and cluster membership:
--raft-nodename,--raft-host,--raft-port,--initial-cluster, and--join-existingfor a node that joins a running cluster. See Cluster Identity and Discovery. - Storage:
--storage,--wal-storage,--storage-path, and--wal-path. See Storage and WAL. - Network and TLS: listener ports and
--https-certificate. See Network and TLS. - Replication factor, for larger clusters:
--raft-replication-factor. See Replica Placement. - Backups:
--pitr-backup-dir. See Backups and Point-in-Time Recovery.
The remaining sections are for tuning. Change those options after you measure a specific problem, not in advance.
Boolean options are bare switches: passing the flag turns the option on, and the CLI cannot express false. Options whose default is enabled therefore cannot be turned off from the command line. Check-quorum, the shared executor pool, auto-rejoin, and quiescence each have an environment variable that turns them off, listed in their rows.
See Backend I/O Scheduler for how backend read/write pools relate to Raft WAL I/O.
Network and TLS
| Command Line Option(s) | Description | Default Value |
|---|---|---|
-h, --host | Host option accepted by the CLI. The current Kestrel setup listens on all interfaces for configured HTTP/HTTPS ports. | * |
-p, --http-ports | One or more HTTP ports for external REST traffic. If omitted, Kahuna listens on HTTP port 8081. When --https-certificate is configured, cleartext listeners are not bound unless --allow-plaintext-listener is set. Use --grpc-cleartext-ports for cleartext gRPC. | 8081 |
--https-ports | One or more HTTPS ports for external REST/gRPC traffic. HTTPS is bound only when --https-certificate is configured. Passing HTTPS ports without a certificate is rejected. | 8082 when a certificate is configured |
--grpc-cleartext-ports | One or more cleartext HTTP/2 ports for gRPC without TLS. These listeners are gRPC-only and reject HTTP/1.1. TLS suppresses cleartext listeners unless --allow-plaintext-listener is set. | 8083 for standalone nodes without TLS; none by default when joining a cluster |
--https-certificate | Path to the HTTPS certificate used by Kestrel and trusted for internal HTTPS communication. | empty |
--https-certificate-password | Password for the HTTPS certificate. | empty |
--allow-plaintext-listener | Bind cleartext HTTP and h2c listeners even when an HTTPS certificate is configured. Node-only surfaces still refuse cleartext callers in MutualTls mode. | disabled |
Use --grpc-cleartext-ports for trusted local or private-network deployments that need h2c gRPC without TLS overhead. Do not expose cleartext gRPC on untrusted networks because client request payloads are unencrypted. If --raft-grpc-scheme http:// points inter-node traffic at those ports, Raft and leader-forwarding payloads are also unencrypted.
Node Transport Security
MutualTls authenticates node-to-node Raft traffic and Kahuna's internal key/value, lock, sequence, and two-phase commit forwarding calls. SharedSecret protects Raft only.
See Node Transport Security for certificate layout, routing-hint requirements, listener behavior, and rotation.
| Command Line Option | Description | Default Value |
|---|---|---|
--node-auth-mode | Node-to-node authentication mode: Disabled, SharedSecret, or MutualTls. | Disabled |
--node-shared-secret | Shared secret for node authentication in SharedSecret mode. | empty |
--node-auth-header | Header or metadata name that carries the node signature in SharedSecret mode. Empty keeps Kommander's default. | empty |
--node-require-tls | Reject node-to-node requests that did not arrive over TLS. | true |
--node-auth-clock-skew | Maximum accepted clock skew for signed node requests, in seconds. Applies to SharedSecret mode. | 60 |
--client-certificate | PKCS#12 certificate this node presents to peers in MutualTls mode. Defaults to --https-certificate. | empty |
--client-certificate-password | Password for --client-certificate. Defaults to --https-certificate-password when --client-certificate is not set. | empty |
--trusted-client-cert-thumbprint | SHA-256 thumbprints of peer certificates this node accepts in MutualTls mode. | none |
--trusted-server-cert-thumbprint | SHA-256 thumbprints of peer server certificates this node pins when dialing peers. | system trust store |
Admin Operations Authorization
| Command Line Option | Description | Default Value |
|---|---|---|
--admin-api-key-file | File of admin keys, one per line, each at least 32 characters. Requires a key for node removal, replication-factor changes, range-map changes, backups, backup GC/validation, and restore. Loaded at startup; invalid files stop startup. | none (admin operations open) |
See Admin Operations Authorization for client credentials, scope, and rotation. This is independent of node mTLS.
Health and Readiness
Kahuna exposes GET /v1/cluster/health as a readiness endpoint for load balancers and orchestrators. It returns HTTP 200 only when the node has completed cluster initialization and has a serving cluster role. It returns HTTP 503 while the node is still initializing or is not a member.
The JSON response includes:
| Field | Meaning |
|---|---|
ready | true when the node can serve requests. Mirrors the HTTP status. |
initialized | true after the node has received and applied the cluster partition map. |
localRole | Local membership role, such as Voter, Learner, Leaving, or NotMember. |
hostedPartitions | Number of data partitions hosted locally. Informational only; with replica placement a ready node can host zero partitions and still forward requests. |
fatalFault | Set when the process observed a fatal runtime fault, currently out-of-memory, and was configured not to fail fast. A node with this field set returns 503 for the rest of its process lifetime. |
Use readiness for traffic routing. Membership can be available before the node is initialized, so a node may answer membership queries while still refusing key/value requests.
Status Dashboard
Kahuna serves a read-only Status Dashboard at the HTTP root by default. Open http://host:port/ or https://host:port/ in a browser to inspect node identity, readiness, storage, replication factor, hosted partitions, backup configuration, and selected engine metrics.
| Command Line Option | Description | Default Value |
|---|---|---|
--disable-dashboard | Disable the browser dashboard and restore the root response to plain Kahuna.Server. | disabled |
--dashboard-refresh-seconds | Browser polling interval in seconds. Values are clamped between 1 and 300. | 5 |
The dashboard is intentionally read-only. It does not start backups, move replicas, split ranges, or write cluster state. The JSON endpoints behind it are:
| Endpoint | Meaning |
|---|---|
GET /v1/dashboard/summary | Node identity, readiness, hosted partition count, cluster mode, replication factor, storage paths, backup status, version, uptime, heap bytes, thread count, and refresh interval. |
GET /v1/dashboard/metrics | Curated in-process metrics from Kahuna and Kommander, capped for browser polling. |
Client Routing Hints
Kahuna can include advisory route hints in REST and gRPC responses. The .NET and TypeScript clients can use those hints to send repeated key/value, lock, and sequence operations directly to the node that currently owns the resource, avoiding an extra inter-node forward.
| Command Line Option | Description | Default Value |
|---|---|---|
--advertised-client-endpoint | Base URL this node advertises to clients in routing hints, for example https://node1:8082. If empty, Kahuna derives it from the Raft endpoint and --advertised-client-scheme. Set it explicitly when the Raft address is not client-reachable. | derived |
--advertised-client-scheme | URL scheme prepended to peer Raft endpoints when deriving peer client URLs. Empty follows --raft-grpc-scheme. | follows --raft-grpc-scheme |
--disable-peer-endpoint-advertisement | Never name a peer in a routing hint. Use this when peer client URLs cannot be derived from peer Raft endpoints. | disabled |
--disable-routing-hints | Do not return advisory routing hints. Clients then keep their configured endpoint selection. | disabled |
The route is always advisory: the receiving server re-resolves the resource and checks leadership before executing. See Client Leader-Aware Routing for client modes, endpoint mapping, metadata mode, and metrics.
Storage and WAL
| Command Line Option | Description | Default Value |
|---|---|---|
--storage | Materialized Kahuna state backend for persistent locks, key/value entries, revisions, and sequences. Built-in values are rocksdb, sqlite, and memory; an extension can register another name. | rocksdb |
--storage-path | File system path for materialized state storage. Use a durable local disk for rocksdb or sqlite. If omitted, Kahuna resolves it under KAHUNA_HOME/data, $XDG_DATA_HOME/kahuna/data, or ~/.local/share/kahuna/data depending on the environment. | resolved user data path |
--storage-revision | Revision name used to select a materialized state database or file set under --storage-path. If omitted, the server uses v1 so restarts reopen the same data set. | v1 |
--wal-storage | Raft WAL backend used by Kommander. Built-in values are rocksdb, sqlite, and memory; an extension can register another name. | rocksdb |
--wal-path | File system path for Raft WAL storage. Use a durable local disk. If omitted, Kahuna resolves it under KAHUNA_HOME/wal, $XDG_DATA_HOME/kahuna/wal, or ~/.local/share/kahuna/wal depending on the environment. | resolved user data path |
--wal-revision | Revision name used to select the WAL database or file set under --wal-path. | v1 |
--wal-sync-writes | Keep synchronous durable WAL writes enabled. This is the default behavior. | enabled |
--disable-wal-sync-writes | Disable synchronous durable WAL writes for faster non-critical local or test runs. | disabled |
--rocksdb-shared-memory | Share one RocksDB block cache and write-buffer manager when both storage layers use RocksDB. Requires positive shared cache and memtable budgets. | disabled |
--storage-shared-cache-mb | Cache budget in MiB available to both storage layers. With shared RocksDB memory, this is the total block-cache budget. | 0 (none) |
--storage-shared-memtable-budget-mb | Shared memtable budget in MiB. When a shared cache is set, this is charged inside it and must not exceed it. | 0 (none) |
--storage-compaction-rate-mbps | Throughput budget in MB/s for materialized store flush and compaction writes. The built-in RocksDB backend applies it; SQLite and memory ignore it. | 0 (unlimited) |
--storage-max-background-compactions | Maximum concurrent materialized store compactions. The built-in RocksDB backend applies it; SQLite and memory ignore it. | 0 (backend default) |
--disable-rocksdb-direct-reads | Disable RocksDB direct I/O reads for the materialized state backend and use buffered reads through the operating-system page cache. Direct reads are enabled by default. Applies only when --storage is rocksdb. | disabled |
--rocksdb-statistics | Enable RocksDB internal statistics collection and LOG dumps every 60 seconds for tuning or diagnosis. This adds per-operation overhead. Applies only when --storage is rocksdb. | disabled |
--rocksdb-shared-memory-budget-mb and --rocksdb-shared-memtable-budget-mb remain accepted as legacy aliases when the corresponding --storage-shared-* option is absent. Their former implicit defaults of 320 MiB and 128 MiB no longer apply: set both budgets explicitly when enabling shared RocksDB memory. See Storage Engines for sizing and compaction trade-offs.
Cluster Identity and Discovery
| Command Line Option | Description | Default Value |
|---|---|---|
--initial-cluster | Static discovery list for the initial Raft cluster. Pass one or more node addresses. | none |
--join-existing | Join a running cluster as a new learner using --initial-cluster as the seed list. | disabled |
--graceful-leave-on-shutdown | Commit removal of this member during planned shutdown instead of waiting for SWIM eviction. Do not enable for rolling restarts because the node is removed from membership. | disabled |
--initial-cluster-partitions | Number of Raft partitions created for the initial cluster. | 3 |
--raft-nodename | Human-readable node name used by Raft. If omitted, the server uses the machine name. | machine name |
--raft-nodeid | Numeric node identifier used by Raft. | 0 |
--raft-host | Host advertised for Raft consensus and replication traffic. | localhost |
--raft-port | Port advertised for Raft consensus and replication traffic. | 8081 |
Replica Placement
Replication factor controls which nodes host each partition. 0 keeps the default full-replication mode where every roster voter hosts every partition. A positive value creates explicit per-partition replica sets. See Replication Factor and Replica Placement for rollout, placement inspection, backup behavior, and migration notes.
| Command Line Option | Description | Default Value |
|---|---|---|
--raft-replication-factor | Desired voter replicas per partition. 0 means full replication. Prefer odd values such as 3 or 5. | 0 |
--raft-enable-placement-rebalancer | Enable ongoing replica-placement repair and balancing on the leader of partition 0 (the system partition). Initial placement still applies when --raft-replication-factor is positive. | disabled |
--raft-placement-pass-interval | Interval between placement-controller passes on the partition 0 leader, in milliseconds. 0 disables the timer, but commit-triggered passes still run. | 5000 |
--raft-max-replica-moves-per-pass | Maximum new replica add/remove sequences started in one placement-controller pass across repair and balance priorities. | 4 |
--raft-max-concurrent-replica-transfers | Maximum partitions with an in-flight learner catch-up or replica removal caused by balance moves. Durability repair uses a separate budget. | 1 |
--raft-max-concurrent-replica-repairs | Maximum in-flight repair moves for under-replicated partitions or replicas stranded on departed nodes. | 3 |
--raft-decommission-drain-timeout | Graceful-leave wait time, in milliseconds, for evacuating this node's placed replicas before removal. On timeout the node stays in the roster and reports DrainTimedOut. | 120000 |
--raft-replica-count-deadband | Replica-count imbalance tolerated before balance moves start. Under-replicated partitions bypass this deadband. | 1 |
--raft-zone | Optional zone or rack hint for the local node. Placement prefers spreading replicas across distinct zones. | empty |
--raft-enable-load-reports | Gossip per-partition load reports even when no other feature enabled them. Load reports are enabled automatically by leader balancing, placement rebalancing, or a positive replication factor. | disabled |
Workers and Runtime
| Command Line Option | Description | Default Value |
|---|---|---|
--locks-workers | Number of lock actors per durability ring. 0 auto-sizes to max(32, CPU cores * 4). | 0 |
--keyvalue-workers | Number of key/value actors per durability ring. 0 auto-sizes to max(32, CPU cores * 4). | 0 |
--sequencer-workers | Number of sequence actors. 0 auto-sizes to max(8, CPU cores). | 0 |
--sequencer-block-size | Values reserved per sequence compare-and-set (CAS) for sequences without their own blockSize. Larger blocks amortize one Raft commit across more sequence values but can leave larger gaps if a block is abandoned. | 1000 |
--sequencer-idempotency-retention-max | Maximum idempotency entries retained per sequence record. 0 disables the count cap. | 256 |
--sequencer-idempotency-retention-ttl | Seconds within which retrying a keyed sequence reservation replays the same allocation. 0 disables age pruning. | 600 |
--sequencer-max-sequences-per-actor | Maximum resident sequences per actor before least-recently-used sequence state is evicted. 0 is unbounded. | 10000 |
--sequencer-block-lease | Seconds a reserved sequence block may be served from memory before revalidating against the durable record. Safe sequence updates wait this long and refuse new allocations during the wait. 0 disables revalidation and therefore refuses sequence updates. | 5 |
--background-writer-workers | Number of background persistence writer workers. Values less than or equal to 0 are normalized to 1. | 1 |
--backend-read-io-threads | Dedicated Kahuna backend read pool threads for point gets, existence checks, read-before-write work, and scans. Separate from the Raft WAL read pool. Must be positive; the node refuses to start with 0 or a negative value. | 8 |
--backend-write-io-threads | Dedicated Kahuna backend writer pool threads for background batch writes and pruning. The background writer submits every batch to a single queue, so writes run one at a time and values above 1 only add idle threads. Must be positive; the node refuses to start with 0 or a negative value. | 1 |
--backend-read-queue-depth | Per-partition pending queue depth for the backend read scheduler before reads receive retryable backpressure. | 4096 |
--default-transaction-timeout | Default transaction timeout in milliseconds. | 5000 |
--max-concurrent-transactions | Script transactions that may execute concurrently before further ones queue and start in priority order. 0 disables the script admission gate. | 0 |
--max-concurrent-sessions | Interactive transaction sessions that may be open concurrently before further ones queue and start in priority order. 0 disables the session admission gate. | 0 |
--transaction-priority-reserved-slots | Slots out of each transaction concurrency ceiling that only High and Critical transactions may occupy. | 0 |
--transaction-priority-aging-threshold | Milliseconds a queued transaction waits to gain one effective priority level. 0 disables aging. | 1000 |
--transaction-priority-max-queued | Callers that may wait for an admission slot per gate before further ones receive AdmissionRefused. 0 makes the queue unbounded. | 4096 |
--default-admission-wait | Milliseconds a caller waits for an admission slot when it does not request its own budget. This is separate from transaction lifetime. | 5000 |
--max-admission-wait | Maximum admission wait in milliseconds. Caller-supplied waits are clamped to this value. | 30000 |
--script-cache-expiration | Script parser cache expiration in seconds. | 600 |
--max-script-length | Largest transaction script accepted, in bytes. Oversized scripts are refused before parsing. | 65536 |
--max-script-depth | Deepest transaction script syntax tree accepted. This bounds parser and evaluator stack use for deeply nested expressions or very long statement lists. | 256 |
--disable-script-actor-turns | Run every script on the general transaction path. By default, eligible auto-commit scripts over one ephemeral key run inside one actor turn. | disabled |
--disable-fused-ephemeral-finalize | Finalize every ephemeral transaction with separate prepare, range-lock probe, and commit messages. By default, a transaction whose whole write set is one ephemeral key can finalize in one actor turn. | disabled |
--extension-assembly | Path to an assembly publishing user-defined script functions through IKahunaFunctionProvider, or storage engines for --storage and --wal-storage through IPersistenceBackendProvider and IWalProvider. Repeatable. Every cluster node that may coordinate scripts should load the same function set. Dependencies load from the assembly's directory. An extension cannot replace a built-in storage engine name. The assembly runs as fully trusted code in the server process. See Custom Storage Engines. | none |
--extension-option | Settings for extension storage engines as key=value pairs after one flag, for example --extension-option acme.mode=fast acme.region=west. Values may contain =; duplicate or empty keys stop startup. Kahuna passes the map to storage provider contexts without interpreting it. | none |
--function-slow-warn-ms | Log a warning when a user-defined script function takes longer than this many milliseconds. 0 disables the warning. | 50 |
--revisions-to-cache | Recent revisions retained per key in memory; must be at least 1. Older persistent revisions can fall back to disk; older ephemeral revisions have no disk history. | 4 |
--trim-flushed-revisions | Drop flushed persistent revisions from the resident archive, preserving unflushed history and the snapshot-hold boundary. Historical reads may need more disk I/O. Ephemeral archives are unchanged. | disabled |
--pinned-value-payloads | Copy qualifying committed value payloads to the pinned object heap to avoid later GC relocation; adds an allocation and copy per retained value. | disabled |
--pinned-value-payload-min-bytes | Smallest payload copied when pinned value payloads are enabled, in bytes. | 256 |
--cache-entry-ttl | Age threshold used by lock cleanup and legacy cleanup paths, in seconds. Key/value LRU eviction is budget-based. | 1800 |
--cache-entries-to-remove | Maximum entries removed by cleanup paths that use this cap. Values less than or equal to 0 are normalized from the key/value collection batch size. | 100 |
--dirty-objects-writer-delay | Delay between dirty object writer flush passes, in milliseconds. | 200 |
--checkpoint-interval | Period, in seconds, at which dirty partitions checkpoint after flushes so the Raft WAL retention floor can advance and old log entries can compact. | 30 |
--fail-fast-on-oom | Terminate the process on OutOfMemoryException so an orchestrator restarts the node with a clean heap. Enabled by default; the server CLI cannot turn it off. | enabled |
Client Request Limits
These bounds apply at REST/gRPC key/value entry points, including the client batch stream. 0 disables each bound. See Key/Value Request Limits for refusals, transaction accounting, and transport constraints.
| Command Line Option | Description | Default Value |
|---|---|---|
--max-key-bytes | Maximum UTF-8 key size on set/set-many and transaction lock acquisition. | 16384 |
--max-value-bytes | Maximum value or compare-value payload on set/set-many, in bytes. | 4194304 |
--max-batch-items | Maximum items in a client set/delete/get/exists-many or many-lock call. Oversized batches are refused whole. | 20000 |
--max-transaction-mutations | Separate limits for written keys and acquired locks in client sessions and script transactions. | 20000 |
--snapshot-hold-max-lease-ms | Longest lease accepted on snapshot-hold acquire or renew, in milliseconds. | 86400000 (one day) |
--snapshot-hold-max-per-holder | Maximum snapshot holds registered by one holder. | 4096 |
--snapshot-hold-max-total | Maximum snapshot holds in the cluster registry. | 65536 |
Key/Value Watch and History
Key/value watches on persistent keys work with the defaults. To resume from a progress watermark after a disconnect, enable the commit admission window on every node with the same value. This also bounds how far a commit timestamp may trail the log entry that carries it; entries outside the window receive a retryable refusal. Choose the bound with your transaction duration and clock skew in mind. See Watch Key Changes for a consumer example.
| Command Line Option | Description | Default Value |
|---|---|---|
--commit-admission-lag-ms | Maximum milliseconds a commit timestamp may trail its log entry. A positive value enables watch progress watermarks and resume. Nodes must run a version that understands this option and use the same value. | 0 (live watches only) |
--history-hold-max-lease-ms | Longest history hold lease, in milliseconds; 0 removes the bound. | 86400000 (one day) |
--history-hold-max-per-holder | Maximum history holds for one holder; 0 removes the bound. | 4096 |
--history-hold-max-total | Maximum history holds in the cluster; 0 removes the bound. | 65536 |
--transaction-origin-tags | Retain a transaction's origin label in its prepared intents and watch events. Enable only when every node understands it. | disabled |
--watch-max-capacity | Largest frame capacity a watch may request. A request above it is refused as invalid, so a caller cannot make the node buffer without bound. | 65536 |
--watch-max-buffered-bytes | Bytes of keys and values one watch may buffer for a slow reader, including frames held back during a replay or behind a pending intent. A watch over the limit ends with an overflow. | 67108864 (64 MiB) |
--watch-max-per-node | Most watches open on the node at once, across every client surface. 0 removes the bound. | 65536 |
--watch-max-per-call | Most watches one gRPC watch call may hold open. One call can carry many watches, and HTTP/2 stream limits do not count them. 0 removes the bound. | 1024 |
--watch-max-concurrent-replays | Most watch replays (one per resumed partition) the node runs at once. A resume that finds no free slot is refused with a retry. 0 removes the bound. | 64 |
History holds keep the relevant partition WAL available for replay until the holds are advanced, released, or purged. They increase log retention and do not guarantee that a resume will succeed if a replica already lost the needed history.
Key/Value Write Coalescing
These options tune persistent partition writes before they are proposed to Raft. Kahuna can combine SET, DELETE, EXTEND, and durable transaction-finalization records for the same partition into one Raft call. See Partition Write Coalescing for behavior, retry semantics, and metrics.
| Command Line Option | Description | Default Value |
|---|---|---|
--kv-write-linger-ms | Delay from the oldest queued persistent partition write before its partition batch is proposed. 0 dispatches an idle partition immediately. | 1 |
--kv-write-post-completion-hold-ms | Optional hold after a partition batch completes before the next sub-threshold batch is dispatched. This can form denser batches under sustained same-partition load. Full batches and queue-age releases are not delayed. | 0 |
--kv-write-precise-wake | Use one dedicated timer thread per node for linger, hold, and queue-age wakes; sleeps whole milliseconds and spins the sub-millisecond remainder. | false |
--kv-write-fill-target-trigger | Dispatch held/lingering buffers when they reach a learned submission-count target; periodic timed batches refresh the target. | false |
--disable-published-head-reads | Disable resident latest point-get reads from immutable published heads; use actor reads for diagnosis. | disabled; published reads enabled |
--kv-write-max-batch-items | Maximum log entries selected for one aggregator Raft call. | 512 |
--kv-write-max-in-flight-batches | Maximum aggregator batches a partition may have awaiting Raft results at once. 1 keeps the serial one-round-at-a-time pipeline. Higher values overlap quorum waits while preserving FIFO dispatch order. | 1 |
--kv-write-max-batch-bytes | Target serialized bytes selected for one aggregator Raft call. An oversized single item dispatches alone. | 4194304 |
--kv-write-max-queued-items | Maximum admitted persistent submissions per partition, including writes already in flight. | 8192 |
--kv-write-max-queued-bytes | Maximum admitted serialized bytes per partition, including writes already in flight. | 33554432 |
--kv-write-max-queue-delay-ms | Maximum pre-dispatch wait before a queued write is released as MustRetry. | 1000 |
--kv-write-aggregator-inbox-size | Ordinary-submission inbox bound per aggregator lane. Control messages are exempt. Values less than or equal to 0 disable the bound. | 16384 |
--persistence-max-unflushed-items | Maximum committed key/value writes held in memory awaiting background flush before ordinary writes receive retryable backpressure. 0 disables the item bound. | 1000000 |
--persistence-max-unflushed-bytes | Maximum value bytes held in memory awaiting background flush before ordinary writes receive retryable backpressure. 0 disables the byte bound. | 536870912 |
--persistence-write-stall-warn-ms | Milliseconds an in-flight backend store write may remain unacknowledged before Kahuna logs a stall warning. 0 disables the log warning, but the stall metrics are still published. | 500 |
Durable transaction decision, materialization, settlement, recovery, and range-metadata handoff records use terminal scheduler admission with reserved headroom. The terminal reserve and node-global queue settings are KahunaConfiguration fields and are not exposed as server command-line flags.
Key-Range Split and Merge
These options tune automatic splitting and merging for key spaces registered with key-range sharding. 0 disables the corresponding automatic trigger where noted.
| Command Line Option | Description | Default Value |
|---|---|---|
--range-split-threshold | Sampled key count above which a key range is split automatically. 0 disables count-based auto-split. | 1000 |
--range-split-min-range-size | Minimum number of keys each half must hold for an automatic split to proceed. | 10 |
--range-split-settle-window | Seconds a freshly split range must settle before it can split again. Must be at least --raft-min-leader-stability-ms. | 10 |
--range-move-settle-timeout | Maximum seconds a split or merge waits under quiesce for in-flight transactions in the moving range to decide and settle before cutover. Writes into the moving range are refused retryably during this window. 0 disables the wait. | 10 |
--range-move-quiesce-ttl | Maximum seconds a split/merge write fence may remain active. A move that exhausts the window refuses cutover with QuiesceExpired. Values below 1 second are raised to 1 second. | 30 |
--raft-max-partitions | Maximum data partitions, enforced by the system-partition leader. 0 is unbounded; otherwise must be at least --initial-cluster-partitions. Set consistently on all nodes. | 0 |
--range-max-ranges-per-key-space | Maximum ranges per key space. 0 removes the quota. A split at either capacity bound returns PartitionLimitReached. | 0 |
--range-merge-min-size | Key count below which adjacent ranges become eligible for automatic merge. 0 disables auto-merge. | 10 |
--range-collection-interval | Seconds between range split/merge sampling passes. Also affects key/value collection, prepared-intent recovery, and session range-lock renewal. | 60 |
--range-split-load-threshold | Sustained replicated write operations per second required before a range becomes a load-split candidate. 0 disables load-based auto-split. | 0 |
--range-split-load-min-queue-depth | Minimum WAL queue depth required alongside the load threshold. | 8 |
--range-split-load-window | Seconds the load predicate must hold continuously before a load split is triggered. | 15 |
--range-split-load-poll-interval | Seconds between load-signal polls. Keep below --range-split-load-window. | 5 |
Backups and Point-in-Time Recovery
| Command Line Option | Description | Default Value |
|---|---|---|
--pitr-window | Recoverable WAL history in seconds: how far back a restore target may be. Values are normalized at startup: a non-positive value becomes 3600 (one hour) and a value over 21600 (6 hours) is capped at 21600. Increasing this value increases retained WAL storage. | 3600 |
--base-snapshot-interval | Intended interval between base checkpoints per partition, in seconds. A shorter interval reduces WAL replay during restore. Values are normalized at startup: a non-positive value becomes 1800 (30 minutes) and a value longer than --pitr-window is reduced to the window. This setting contributes to the protected WAL floor but does not schedule backups automatically. | 1800 |
--pitr-backup-dir | Root directory for backup catalog manifests and artifacts. Kahuna creates it when needed. Backup REST/gRPC, client, and CLI operations are disabled when this is empty. It is required by --pitr-bootstrap-from. | empty |
--pitr-backup-target | Backup storage target. local stores manifests and artifacts under --pitr-backup-dir. Other values require a host-registered backup storage provider. | local |
--pitr-backup-scratch-dir | Local staging directory used when the selected backup target cannot be written to directly by the storage engine. Size it for one full backup. | empty |
--pitr-backup-cluster-id | Operator-assigned cluster identity stamped into backup manifests. Set the same value on every node to prevent cross-cluster chain resolution. | empty |
--pitr-backup-mac-key-file | Path to the HMAC-SHA-256 key file used to authenticate backup manifests. Deploy the same key contents to every node, keep it outside --pitr-backup-dir, and make it readable only by the server user. | empty |
--pitr-restore-root | Server-owned root directory that restore targets must be contained within. Setting this enables confined remote restore. | empty |
--pitr-allow-unconfined-remote-restore | Allows remote restore requests without --pitr-restore-root. Use only for trusted administrative environments; do not enable it on shared nodes. | false |
--backup-retention-max-chains | Keep at most this many most-recent backup chains. 0 is unbounded and retention remains off unless at least one retention bound is set. | 0 |
--backup-retention-max-age | Delete chains whose newest backup is older than this many seconds. 0 is unbounded. | 0 |
--backup-retention-max-bytes | Keep the most-recent backup chains whose artifact bytes fit this budget. The newest chain is always kept. 0 is unbounded. | 0 |
--backup-gc-interval | Periodic backup GC cadence in seconds. A pass also runs after each backup. 0 disables the periodic pass only. | 3600 |
--backup-capture-throttle-mbps | Per-capture disk-work budget in decimal MB/s for the RocksDB as-of trim, hash/verify reads, and staged-image copy. Trades backup duration for lower foreground I/O contention; not a node-wide I/O or latency limit. 0 is unlimited. | 0 |
--backup-apply-barrier-timeout-seconds | Full-capture wait for committed writes to apply; timeout reports lagging partitions as retryable PartitionCaptureFailed. Non-positive values use 30 seconds. | 30 |
--backup-restore-throttle-mbps | Throughput budget for the restore checkpoint copy in MB/s. 0 is unlimited. | 0 |
--pitr-bootstrap-fallback-to-join | Skip an out-of-window seed or a latest selection with no valid chain and join through normal catch-up. Does not restore invalid candidates or ignore explicit-chain authentication/corruption failures. | false |
--pitr-bootstrap-from | Leaf backup GUID or latest. On an empty RocksDB/SQLite store, copy and verify the full base image before opening the backend, replay incrementals, certify WAL boundaries, then join. Requires --join-existing, --initial-cluster, and --pitr-backup-dir. See PITR Bootstrap. | none |
--pitr-target-time-ms | PITR target using the physical HLC component in Unix epoch milliseconds. 0 restores through the selected chain's natural end. | 0 |
See Backups and Point-in-Time Recovery for setup, client and CLI usage, the backup-chain model, and recovery constraints.
Persistent Revision Retention
| Command Line Option | Description | Default Value |
|---|---|---|
--persistent-revision-retention-count | Maximum persisted key/value revisions to keep per key. 0 keeps revisions forever. | 0 |
--persistent-revision-retention-age | Maximum age of persisted key/value revisions in seconds. 0 disables age-based retention. | 0 |
--persistent-revision-cleanup-interval | Minimum interval between full persistent revision cleanup sweeps, in seconds. | 300 |
--persistent-revision-cleanup-batch-size | Maximum revision records deleted per cleanup pass. | 10000 |
--persistent-revision-cleanup-time-budget | Wall-clock budget, in milliseconds, for one targeted persistent revision cleanup pass during a flush cycle. Keys not reached stay queued for the next cycle. | 250 |
--persistent-revision-cleanup-on-write | Keep targeted persistent revision cleanup after writes enabled. This is the default behavior. | enabled |
--disable-persistent-revision-cleanup-on-write | Disable targeted persistent revision cleanup after writes. | disabled |
Persistent revision cleanup is clamped by live snapshot holds. A held snapshot timestamp keeps the boundary revision needed by that timestamp, and every newer revision, even if the count or age retention settings would otherwise prune them.
Durable Transaction Retention
These options bound retained durable two-phase-commit metadata. Terminal records and completion receipts are kept long enough for duplicate finalize calls and recovery to produce the correct answer, then reclaimed by age, count, byte budget, or heap-pressure policy.
| Command Line Option | Description | Default Value |
|---|---|---|
--durable-record-retention-max | Maximum resident terminal durable transaction records retained per node before older records are reclaimed early. 0 disables the count budget. | 200000 |
--durable-record-retention-max-bytes | Estimated heap-byte budget for resident terminal durable transaction records plus completion receipts. 0 disables the byte budget. | 268435456 |
--durable-record-retention-heap-pressure | Managed-heap load ratio above which terminal records older than the retention floor are reclaimed aggressively. 0 disables this pressure valve. | 0.85 |
--durable-record-retention-floor | Minimum age, in seconds, below which a terminal durable record is not reclaimed early by count, byte, or heap-pressure budgets. Kahuna raises it when needed to cover the decision-deadline recovery horizon. | 90 |
--durable-maintenance-interval | Seconds between durable transaction maintenance ticks, including prepared-intent recovery and terminal record retention sweeps. 0 uses the collection interval. | 5 |
Raft Communication
Snapshot receive staging, deadline, compatibility, and compression flags (--raft-snapshot-max-pending-bytes, --raft-snapshot-max-pending-sessions, --raft-snapshot-receive-session-ttl, --raft-snapshot-staging-directory, --raft-snapshot-staging-memory-bytes, --raft-snapshot-chunk-ack-timeout, --raft-snapshot-transfer-step-timeout, --raft-reseed-request-timeout, --raft-allow-legacy-snapshot-senders, and --raft-grpc-enable-snapshot-compression) are documented in Snapshot Options.
| Command Line Option | Description | Default Value |
|---|---|---|
--read-io-threads | Number of Raft WAL read I/O threads. Kahuna backend reads use the separate backend read pool. | 4 |
--write-io-threads | Number of Raft write I/O threads. | 16 |
--raft-enable-shared-executor-pool | Share a bounded worker pool across Raft partitions instead of using one OS thread per partition. Useful for very high partition counts. Set KAHUNA_SHARED_POOL=0 to fall back to one thread per partition, for diagnostics. | enabled |
--raft-executor-pool-size | Number of shared Raft executor workers. 0 auto-sizes to the processor count. | 0 |
--raft-http-scheme | HTTP scheme used by Raft REST communication. | https:// |
--raft-http-auth-bearer-token | Bearer token sent with Raft REST communication. | empty |
--raft-http-timeout | Raft REST request timeout in seconds. | 5 |
--raft-http-version | HTTP protocol version used by Raft REST communication. | 2.0 |
--raft-grpc-scheme | URL scheme prepended to bare peer endpoints when opening Raft gRPC channels. Kahuna inter-node gRPC forwarding uses the same scheme so Raft traffic and leader-forwarded key/value, lock, and sequence calls dial peers consistently. Use http:// only when peers advertise cleartext HTTP/2 ports. | https:// |
--raft-grpc-channels-per-node | Pooled gRPC channels opened per peer. Values are clamped between 1 and 64; each channel holds a connection and handler for the process lifetime. | 4 |
--raft-grpc-enable-multiple-http2-connections | Allow each pooled gRPC channel to open multiple HTTP/2 connections for additional concurrent streams. | disabled |
--raft-grpc-max-message-bytes | Largest gRPC message this node accepts from or sends to a peer. Raise on every receiver before increasing outbound or backfill batch byte caps beyond it. | 16777216 |
--raft-grpc-enable-append-logs-coalescing | Coalesce multiple AppendLogs calls into one gRPC frame per write cycle for write-heavy multi-partition workloads. | disabled |
--raft-grpc-append-logs-max-coalesce-batch | Maximum AppendLogs items drained into one coalesced gRPC frame when coalescing is enabled. | 256 |
--raft-allow-insecure-certificate-validation | Skip TLS certificate validation for inter-node Raft gRPC traffic. Use only in development or test environments. | disabled |
--raft-max-pre-auth-request-body-bytes | Maximum Raft REST request body buffered before authentication, in bytes. Bounds unauthenticated memory use independently of host limits. | 33554432 |
--raft-max-outbound-queue-bytes-per-peer | Maximum buffered outbound bytes queued per peer before excess AppendLogs entries are dropped and later resent by heartbeat or backfill retry. 0 disables the cap. | 67108864 |
--raft-max-outbound-batch-bytes | Maximum log payload bytes packed into one peer batch request. Also bounds an AppendLogs coalescing frame. Must stay below --raft-grpc-max-message-bytes. Values less than or equal to 0 disable the byte cap. | 4194304 |
--raft-max-backfill-bytes-per-round | Maximum payload bytes sent in one backfill round, in addition to the entry-count cap. Keeps large-value catch-up batches bounded. | 4194304 |
--raft-snapshot-rescue-max-consecutive-cycles | Consecutive snapshot-rescue cycles that can still leave a follower below the compaction floor before the convergence breaker pauses that peer. Values less than or equal to 0 disable the breaker. | 3 |
--raft-snapshot-rescue-probe-interval | Probe interval, in milliseconds, while the snapshot-rescue breaker is open. A probe lets a recovered follower be reseeded eventually. Values less than or equal to 0 disable probing. | 300000 |
--raft-snapshot-export-retry-cache-max-bytes | Maximum bytes cached for one produced snapshot export on the leader so retries can resend the same export instead of rebuilding it. Values less than or equal to 0 disable the cache. | 67108864 |
--raft-compaction-live-replica-lag-budget | Entry-count lag budget that protects a live follower after snapshot rescue so normal compaction does not immediately put it below the floor again. Values less than or equal to 0 disable the hold. | 1000000 |
--raft-compaction-live-replica-lag-window | Recent-history window in milliseconds used to raise the live-peer entry budget based on observed commit rate. 0 uses the entry budget alone. | 180000 |
--raft-compaction-live-replica-lag-cap | Maximum entries contributed by that window. Nonpositive disables its increase; it does not lower a larger entry budget. | 10000000 |
--raft-compaction-silent-peer-retention-window | Milliseconds a leader keeps holding WAL compaction for a peer that stopped answering. After the window, the silent peer no longer holds compaction and a restart is seeded by snapshot. 0 disables the hold. | 120000 |
--raft-compaction-durability-clamp-report-interval | Interval in milliseconds for repeated warnings when Raft compaction is held by the application-durability floor. Values less than or equal to 0 keep only start and end logs. | 60000 |
Raft Timing
| Command Line Option | Description | Default Value |
|---|---|---|
--raft-heartbeat-interval | Leader heartbeat interval in milliseconds. | 500 |
--raft-recent-heartbeat | Recent-heartbeat window in milliseconds. | 100 |
--raft-voting-timeout | Vote wait timeout in milliseconds. | 1500 |
--raft-leadership-barrier-timeout | Milliseconds a newly elected leader waits for its promotion barrier entry to commit before stepping down. Raising it tolerates a slower quorum at the cost of failover latency. | 10000 |
--raft-leadership-confirmation-timeout | Maximum milliseconds a read-index leadership confirmation may wait for quorum acknowledgement and applied-frontier catch-up. | 2000 |
--raft-proposal-timeout | Maximum milliseconds a write caller waits for a Raft proposal to reach quorum before the call returns ProposalTimeout. | 10000 |
--raft-wal-stall-step-down-timeout | Maximum milliseconds a leader's own WAL write may stay unanswered before it steps down in the same term. Values less than or equal to 0 disable the watchdog and candidacy gate. | 3000 |
--raft-wal-stall-warn-threshold | Age in milliseconds after which a pending local WAL write is logged as a stall. Peers also use this signal to avoid entry-carrying backfill and snapshot transfers to a stalled node. Values less than or equal to 0 disable local log lines only. | 500 |
--raft-enable-check-quorum | Keep the Raft check-quorum step-down enabled. A leader that has not heard same-term acknowledgement from a majority for the check-quorum window steps down instead of serving from stale leadership. The server switch is on by default; set KAHUNA_CHECK_QUORUM=0 to disable it. | enabled |
--raft-check-quorum-interval-multiplier | Heartbeat intervals without majority acknowledgement before check-quorum steps down a leader. 0 derives the window from the start election timeout. Explicit values must be at least 2 and keep heartbeat interval * multiplier at or below the start election timeout. | 0 |
--raft-self-repair-peer-down-grace | How long promotion-gate self-repair waits while a voter peer is not alive before gap-skipping committed drain or orphaned-tail truncation proceeds, in milliseconds. 0 disables the grace. | 30000 |
--raft-check-leader-interval | Leader check interval in milliseconds. | 250 |
--raft-timer-initial-delay | Initial delay before Raft timers start, in milliseconds. | 2500 |
--raft-update-nodes-interval | Node registry update interval in milliseconds. | 5000 |
--raft-start-election-timeout | Minimum election timeout in milliseconds. | 2000 |
--raft-end-election-timeout | Maximum election timeout in milliseconds. | 4000 |
--raft-start-election-timeout-increment | Minimum election timeout increment in milliseconds. | 100 |
--raft-end-election-timeout-increment | Maximum election timeout increment in milliseconds. | 200 |
--raft-election-timeout-seed | Seed for deterministic election timeouts. 0 means random timing. Intended for testing and reproducibility. | 0 |
Raft Queueing and Batching
| Command Line Option | Description | Default Value |
|---|---|---|
--raft-fan-out-before-local-write | Queue leader WAL write and follower sends concurrently. Quorum completion still waits for local durability; failure after fan-out can leave an unknown outcome. | enabled |
--raft-follower-apply-in-own-turn | Acknowledge follower append before ordered application in separate executor turns. Partition 0 applies inline. | enabled |
--raft-follower-apply-turn-time | Cooperative apply-turn time budget in microseconds, with at least one entry delivered. 0 leaves only the entry budget. A long callback can exceed the time budget. | 100 |
--raft-follower-apply-turn-budget | Entries per follower apply turn. Nonpositive removes the count bound; backlog can increase the effective budget. | 1024 |
--raft-max-queued-client-proposals | Maximum queued client proposals per partition before backpressure applies. | 2048 |
--raft-max-wal-queue-depth-per-partition | Per-partition WAL write queue depth limit. | 4096 |
--raft-max-global-wal-queue-depth | Global WAL write queue depth limit across all partitions. 0 means unlimited. | 0 |
--raft-max-wal-batch-size | Maximum WAL writes grouped into one storage flush. | 256 |
--raft-max-wal-group-batch-partitions | Maximum partitions coalesced into one cross-partition WAL group-commit batch. | 64 |
--raft-wal-group-commit-linger-ms | Optional group-commit linger window in milliseconds. 0 disables linger. | 0 |
--raft-wal-single-fsync-commit | Enable the single-fsync fast path that acknowledges after propose-quorum durability and writes the commit marker lazily. | enabled |
--raft-wal-shard-write-buffer-size-mb | RocksDB Raft WAL shard memtable size in MiB. 0 keeps Kommander's default. Applies only when --wal-storage rocksdb. | 0 |
--raft-wal-shard-min-write-buffer-number-to-merge | Immutable memtables merged into one RocksDB WAL shard flush. 0 keeps Kommander's default. | 0 |
--raft-wal-shard-max-write-buffer-number | Maximum mutable plus immutable memtables per RocksDB WAL shard. 0 keeps Kommander's default. | 0 |
--raft-wal-shard-level0-file-num-compaction-trigger | Level-0 file count that triggers compaction for RocksDB WAL shard column families. 0 keeps Kommander's default. | 0 |
--raft-wal-shard-level0-slowdown-writes-trigger | Level-0 file count at which RocksDB starts slowing WAL writers. 0 keeps Kommander's default. | 0 |
--raft-wal-shard-level0-stop-writes-trigger | Level-0 file count at which RocksDB stops WAL writers. 0 keeps Kommander's default. | 0 |
--raft-wal-shard-max-bytes-for-level-base-mb | RocksDB max_bytes_for_level_base for WAL shard column families, in MiB. 0 keeps RocksDB or Kommander defaults. | 0 |
--raft-wal-shard-universal-compaction | Use universal compaction instead of leveled compaction for RocksDB WAL shard column families. | disabled |
--raft-sqlite-wal-shard-count | SQLite WAL shard databases used to distribute partitions. 0 resolves to the processor count when storage is first initialized. | 0 |
--raft-max-drain-quantum-control | Maximum control-plane operations drained per executor wake cycle. | 8 |
--raft-max-drain-quantum-replication | Maximum replication operations drained per executor wake cycle. | 4 |
--raft-max-drain-quantum-client | Maximum client operations drained per executor wake cycle. | 2 |
--raft-max-drain-quantum-maintenance | Maximum maintenance operations drained per executor wake cycle. | 1 |
Raft Leader Balancing
| Command Line Option | Description | Default Value |
|---|---|---|
--raft-enable-leader-balancer | Enable advisory leader balancing. Configure it consistently on every cluster node. | disabled |
--raft-leader-balancer-report-interval | Interval between node load reports, in milliseconds. | 5000 |
--raft-leader-balancer-interval | Interval between planning passes on the partition 0 leader, in milliseconds. | 30000 |
--raft-leader-balancer-report-ttl | Maximum accepted load-report age, in milliseconds. Must exceed the report interval. | 20000 |
--raft-count-deadband | Allowed leader-count deviation from the ideal before count balancing starts. | 1 |
--raft-load-imbalance-threshold | Fractional load skew that triggers load-based swaps after counts are balanced. | 0.25 |
--raft-min-leader-stability-ms | Minimum leadership age before a partition is eligible to move, in milliseconds. | 5000 |
--raft-move-cooldown | Delay before the same partition can move again, in milliseconds. | 60000 |
--raft-max-moves-per-pass | Maximum transfer suggestions created in one planning pass. | 4 |
--raft-max-concurrent-transfers | Maximum transfer suggestions tracked concurrently. | 2 |
--raft-suggestion-timeout | Time allowed for a suggested transfer to be confirmed by load reports, in milliseconds. | 15000 |
--raft-leader-balancer-ops-weight | Operations-per-second weight in the partition load score. | 1.0 |
--raft-leader-balancer-queue-weight | Queue-depth weight in the partition load score. | 0.5 |
--raft-enable-slow-node-avoidance | When enabled with the leader balancer, nodes whose WAL commit wait is far above the cluster median are avoided as transfer targets and can have existing leadership drained. | disabled |
--raft-slow-node-multiplier | Ratio above the cluster median commit wait required before a node can be considered slow. | 3.0 |
--raft-slow-node-floor-ms | Absolute commit-wait floor below which a node is never considered slow. | 10.0 |
--raft-slow-node-min-samples | Minimum number of WAL group batches required before slow-node classification is evaluated. | 20 |
--raft-slow-node-observation-ttl | Maximum age, in milliseconds, of a node's last commit-wait observation before it is treated as unknown. | 30000 |
--raft-slow-node-enter-passes | Consecutive balancer passes a node must look slow before being classified slow. | 3 |
--raft-slow-node-exit-passes | Consecutive clean passes before a classified slow node is released. | 6 |
See Leader Balancing for rollout, tuning, metrics, and safety behavior.
Raft Membership and Catch-Up
Admission/initialization and learner promotion have separate join budgets. Promotion is bounded by lack of progress, not total elapsed time; progress includes advancing commit frontiers, newly observed partitions, and snapshot receive/install activity. A post-admission failure attempts best-effort withdrawal; caller cancellation leaves that decision to the caller.
| Command Line Option | Description | Default Value |
|---|---|---|
--raft-backfill-threshold | Committed-entry lag that triggers active follower backfill. | 10 |
--raft-backfill-enabled | Enable leader catch-up batches and snapshot fallback for lagging followers. Enabled by default; the server CLI cannot turn it off. | enabled |
--raft-max-backfill-entries-per-round | Maximum committed entries sent to one stale follower per heartbeat interval. | 128 |
--raft-max-backfill-bytes-per-round | Maximum serialized bytes sent to one stale follower per backfill round, in addition to the entry limit. | 4194304 |
--raft-follower-saturation-backoff | Milliseconds a leader waits before retrying backfill to a peer that reported a saturated WAL queue. | 1000 |
--raft-backfill-no-progress-pause-cap | Maximum exponential pause, in milliseconds, between backfill batches to a follower whose reported commit frontier is not advancing. | 30000 |
--raft-backfill-seeded-catch-up-grace-cap | Cap on the estimated catch-up component of a snapshot-seeded follower's escalation grace, in milliseconds; added to the no-progress pause cap. 0 disables the grace. | 180000 |
--raft-backfill-no-progress-anchor-fallback-ships | Consecutive fruitless backfill shipments before the leader re-anchors the next batch at the follower's reported commit frontier. Values less than or equal to 0 disable this fallback. | 2 |
--raft-join-timeout | Join admission and initialization ceiling, in milliseconds; excludes the learner promotion wait. | 60000 |
--raft-join-promotion-stall-timeout | Maximum milliseconds without catch-up progress while waiting for Voter promotion. Must exceed the learner stable window plus node-update interval. | 300000 |
--raft-learner-promotion-lag | Maximum entries a learner may trail the leader while remaining eligible for voter promotion. | 10 |
--raft-learner-promotion-stall-warning-after | Time in milliseconds before logging the last failed promotion check for a placement-added learner. Diagnostic only. | 30000 |
--raft-learner-promotion-stable-window | Time a learner must remain within the promotion lag on all partitions, in milliseconds. | 3000 |
Raft Gossip, Failure Detection, and Quiescence
| Command Line Option | Description | Default Value |
|---|---|---|
--raft-gossip-interval | Interval between membership anti-entropy gossip rounds, in milliseconds. | 5000 |
--raft-gossip-fanout | Random peers contacted per gossip round. 0 disables gossip. | 2 |
--raft-ping-interval | Interval between SWIM node probes, in milliseconds. 0 disables failure detection, which is invalid while quiescence is enabled. | 1000 |
--raft-ping-timeout | Direct SWIM probe timeout, in milliseconds. | 500 |
--raft-indirect-ping-fanout | Intermediary nodes used for indirect probing after a direct ping timeout. | 2 |
--raft-suspicion-timeout | Time a node may remain Suspect before becoming Dead, in milliseconds. | 5000 |
--raft-dead-member-eviction-grace | Time a dead node remains in the roster before partition 0 commits its removal, in milliseconds. | 30000 |
--raft-enable-auto-rejoin | Let a restarted node that finds itself removed from the roster re-run join against the remaining members. Set KAHUNA_AUTO_REJOIN=0 to turn it off when removed live nodes must stay out. | enabled |
--raft-enable-quiescence | Stop per-partition heartbeats after an idle period and rely on SWIM for node liveness. Requires 0 < --raft-ping-interval < --raft-start-election-timeout. Set KAHUNA_QUIESCENCE=0 to turn it off. | enabled |
--raft-quiesce-after | Required partition idle time before heartbeat quiescence, in milliseconds. | 1500 |
Raft Logging and Compaction
| Command Line Option | Description | Default Value |
|---|---|---|
--raft-slow-state-machine-log | Slow state-machine operation log threshold in milliseconds. | 50 |
--raft-slow-wal-machine-log | Slow WAL state-machine operation log threshold in milliseconds. | 25 |
--raft-invariant-checks | Reaction when a Raft invariant check fails: Off, Log, or Throw. This is diagnostic only and does not change protocol behavior. Release builds default to logging; debug builds default to throwing. | build-dependent |
--raft-compact-every-operations | Number of committed operations between automatic Raft WAL compaction checks. | 10000 |
--raft-compact-number-entries | Number of Raft WAL entries removed per compaction batch. | 100 |
--raft-max-entries-per-compaction | Maximum Raft WAL entries processed per compaction run. | 5000 |
Configuration Notes
--wal-storageand--storageconfigure different layers. WAL storage persists Raft logs; materialized storage persists Kahuna object state after committed operations are applied.- Use stable
--storage-revisionand--wal-revisionvalues for existing data directories. Changing revisions points the server at different local storage files. - RocksDB WAL shard tuning flags apply only when
--wal-storage rocksdb. Numeric0values leave Kommander's shipped defaults in force; invalid combinations are still rejected at startup so a bad tuning value is not hidden by a backend switch. - The server CLI does not expose every
KahunaConfigurationfield. In-memory collector knobs, script-cache entry limits, durable-decision deadline knobs, durable deferred-settlement and prepared-intent bounds, terminal write-aggregator reserve knobs, and some advanced range-split policy internals remain code-level or embedded-node configuration. Transaction priority admission, durable record-retention budgets, and the primary key-range split/merge knobs are exposed as server flags. DurableMaterializeOnResolveandDurableMaterializeByReferenceare core/embedded configuration fields with no server CLI flag. Precise wakes and fill-target dispatch have the server switches listed above.- The embedded node exposes the broader runtime surface, including collector and persistent-revision settings. See Embedded Kahuna Node for the full embedded configuration options.
Snapshot Configuration Semantics
Snapshot acknowledgement, install polling, deadlines, and staging caps are explained in Snapshot Installation and Raft Recovery, together with partial-install behavior and server/embedded differences. Leader-side log retention and compaction holds are explained in Snapshot Catch-Up and Log Retention.
Shared Server Configuration Mapping
Clustered and standalone server startup share the embedded configuration mapping before server-only listener and routing settings are added. Backup/PITR settings, durable-record retention/maintenance, checkpoint interval, published-head reads, and revision retention therefore reach the clustered configuration too. Older releases parsed some of these settings on the clustered path but ignored them, so review existing flags when you upgrade: they take effect on the clustered path. This mapping does not add CLI flags for runtime-only fields.