Configure a node
Applies to: development build 0.1.1. Basic networking and storage flags also exist in the public baseline; capacity protection and newer recovery controls require the development build. Check smkv-server --help on the actual binary.
Configuration entry points
For packaged services, edit /etc/default/smkv and restart deliberately. SMKV_ARGS is an argument list interpreted by systemd, with no shell substitution. For a foreground process, pass the same flags to smkv-server. Sharded nodes also read a JSON cluster map; security uses a separate optional JSON file.
SMKV_ARGS="--bind 127.0.0.1:7379 --metrics-bind 127.0.0.1:9108 --partitions 16 --workers 4 --max-entries 100000 --max-log-bytes 1073741824"
This example is an environment-file line, not a command that starts the server. It preserves small evaluation limits, not production sizing.
Core settings
| Flag | Default | Meaning |
|---|---|---|
--partitions |
16 | Fixed logical partitions; cannot change when reopening data |
--workers |
4 | Dedicated storage threads; may change across restarts |
--queue-capacity |
64 | Bounded requests per storage worker |
--max-connections |
128 | Concurrent TCP connection bound |
--max-entries |
100000 | Node indexed-entry budget, split across partitions |
--max-log-bytes |
1073741824 | Node retained-log budget, split across partitions |
--segment-bytes |
67108864 | Segment rotation target; a larger record can occupy its own segment |
--expiry-interval-ms |
100 | Paced expiration maintenance; 0 disables it |
--metrics-bind |
Disabled unless supplied | Private HTTP Prometheus listener |
Default maximum key size is 1 KiB and value size is 1 MiB. Size your workload within the configured limits, including table/key and row-encoding overhead. Choose workers no greater than the partition count.
Plan per-node capacity
Entry/log budgets are node totals, not per-partition settings. RF2 stores two copies across the cluster. Count owned primary and replica entries when sizing each node. Unused quota in one partition is not freely shared with another. Maps can declare different node budgets; each partition uses the smaller quota supported by its two owners.
Retained logs include old values and deletes, not just live payload bytes. Checkpoints, incoming replicas, and ownership transfers require temporary disk and memory headroom. An index estimate is not RSS; include allocator, history, networking, and copy overhead. RAM of 32–128 GB does not imply a fixed safe record count. Measure with representative keys and payloads.
Preserve headroom
Linux development servers sample physical disk, inodes, process RSS, available host memory, and applicable cgroup-v2 memory limits. Normal puts preserve a floor plus a maintenance reserve; maintenance can use the reserve but must preserve the floor.
| Flag | Default bytes |
|---|---|
--capacity-disk-floor-bytes |
67108864 |
--capacity-disk-reserve-bytes |
1073741824 |
--capacity-memory-floor-bytes |
268435456 |
--capacity-memory-reserve-bytes |
536870912 |
--capacity-resume-margin-bytes |
134217728 |
--capacity-max-rss-bytes |
0 (additional RSS ceiling disabled) |
--maintenance-log-percent reserves 5% of logical log quota by default. These are available-byte thresholds, not used-space percentages. There is no automatic eviction. Larger copies may require substantially more headroom than these defaults.
smkv-ctl --seed 10.0.0.11:7381 capacity --json
States are normal, pressure, and writes_blocked. Reads remain routable under capacity pressure. Missing or stale resource samples reject mutations. Non-Linux servers default to disabled physical sampling; startup index reconstruction is not memory-bounded by the governor.
Apply changes deliberately
Record the existing arguments, stop the affected service, edit configuration, and restart. Check logs, readiness, replica progress, and capacity before moving to another node. Do not lower logical quotas below stored data. Do not delete manifests, locks, segments, or identity files to make a new configuration start.