Server Configuration Reference
Every command-line flag accepted by the veltrixdb server binary (cmd/server), grouped by subsystem, with defaults and behavior confirmed against source.
All flags are standard Go flag package syntax: -flag value, -flag=value, or --flag value are all accepted. Boolean flags can be set bare (-encrypt-at-rest) to mean true. Run veltrixdb -help to print the full built-in flag listing from the running binary, which is always the source of truth if this page and the binary disagree.
Two binaries, one flag surface The
veltrixdb server process (cmd/server/main.go) is the only process that reads these flags at startup. Operator tools like veltrix and the admin API configure themselves separately and talk to a running server over TCP/HTTP.
Network
Flags controlling listen addresses for the data plane (binary/text protocol) and the operator plane (metrics, health, admin API).
| Flag | Default | Description |
|---|---|---|
-addr | :9000 | TCP address for the plaintext client listener (text protocol + binary protocol, auto-detected per connection). |
-metrics-addr | :2112 | HTTP address serving /metrics, /healthz, /readyz, /admin/*, and /traces. This is the "admin port" referenced throughout the docs. |
-tls-addr | :9443 | TCP address for the TLS client listener. Only started when -tls-cert and -tls-key are both set; runs concurrently with the plaintext listener on -addr. |
-node | node-1 | Legacy node identifier flag. Superseded by -node-id when both are set. |
Storage
Flags controlling data directories, cache sizing, and engine tuning presets.
| Flag | Default | Description |
|---|---|---|
-data | ./veltrixdb-data | Single data directory (WAL + segments). Ignored whenever -data-dirs is set. |
-data-dirs | (empty) | Comma-separated NVMe mount paths, one per physical disk, e.g. -data-dirs=/mnt/nvme0,/mnt/nvme1,...,/mnt/nvme7. Each disk gets its own segment writer and compaction goroutine; the WAL is placed on the first listed disk. Overrides -data. |
-raw-vlogs | (empty) | Linux only. Comma-separated raw NVMe block-device paths for VLog backing (e.g. /dev/nvme0n1,/dev/nvme1n1,...), paired index-by-index with -data-dirs. Bypasses XFS for VLog I/O; WAL and segment files remain on -data-dirs. Requires CAP_SYS_RAWIO or root. First open writes a 4 KB superblock at offset 0 of each device. Entry count must exactly match -data-dirs. |
-cache | 256 | LIRS cache size in MB. Ignored when -auto-tune is set (hardware-derived value wins), and overridden by the -read-heavy preset's 400 GB default unless you explicitly pass a non-default -cache value alongside it. |
-gc-threshold | 0.30 | VLog dead-space ratio (0.0–1.0) that triggers background compaction. Lower values trigger more frequent, smaller GC passes. |
-auto-tune | false | Auto-detects hardware (RAM, CPU cores, disk types) and self-tunes cache size, memtable size, shard count, compaction threads, and SSTable size (the "80% RAM rule"), plus applies OS-level tuning (NVMe I/O scheduler, hugepages, CPU governor). Requires root or CAP_SYS_ADMIN on Linux for the sysctl/rlimit changes; falls back to defaults with a logged warning if hardware detection fails. |
-read-heavy | false | Applies the read-heavy preset: 400 GB cache, LIRS ratio 0.95, 300s GC interval, 60s TTL scan interval. Tuned for P99 < 5 ms at 2M+ ops/sec on n2-highmem-64-class hardware. Overrides DefaultStorageConfig but not -auto-tune or explicit per-flag overrides applied afterward. |
-scrub-mb-per-sec | 50 | Background CRC32C integrity scrubber bandwidth cap, per disk, in MB/s. 0 disables the scrubber entirely. |
Durability
Flags controlling the write-ahead log, group-commit windows, and point-in-time-recovery (PITR) archiving.
| Flag | Default | Description |
|---|---|---|
-wal-flush-window-ms | 15 | WAL group-commit flush window in milliseconds. At the 15 ms default, roughly 200 entries batch per fdatasync at 100K writes/s. Use a smaller window (e.g. 5 ms) for latency-sensitive workloads at the cost of fewer entries per sync. Must match -vlog-flush-window-ms (an enforced invariant). |
-vlog-flush-window-ms | 15 | VLog fdatasync group-commit window in milliseconds. Must equal -wal-flush-window-ms — WAL and VLog flushes race concurrently, and end-to-end P99 is the max of the two. |
-wal-max-batch | 4096 | Maximum WAL entries per group-commit flush before the flush timer is forced to fire early. Raise this if sustained write rate exceeds window × max_batch (e.g., 100K/s × 0.005s = 500, so 4096 gives generous headroom). |
-archive-dir | (empty) | Root directory for continuous WAL archiving used by point-in-time recovery. Empty disables archiving. When set, a background archiver copies newly-durable WAL entries into <dir>/disk<N>/. |
-archive-interval-ms | 1000 | Poll interval (ms) for the WAL archiver to check for newly durable entries. |
-archive-max-age-sec | 0 | Prune archived WAL segments older than this many seconds. 0 = keep forever. |
-archive-max-bytes | 0 | Prune the oldest archived segments once total archive size exceeds this many bytes. 0 = unlimited. |
See Backup & Restore for how archived WAL segments combine with a full backup during veltrixdb-backup restore-pitr.
Security
Flags controlling TLS, RBAC authentication, at-rest encryption, and the audit log.
| Flag | Default | Description |
|---|---|---|
-tls-cert | (empty) | Path to the TLS server certificate PEM file for client connections. Enables the TLS listener on -tls-addr when set together with -tls-key. |
-tls-key | (empty) | Path to the TLS server private key PEM file. |
-tls-ca | (empty) | Path to a CA certificate for mTLS client verification on the client-facing TLS listener. When set, connecting clients must present a certificate signed by this CA. |
-auth-config | (empty) | Path to an RBAC auth config JSON file (users, password hashes, roles). When set, the AUTH command is required before any operation on that connection. When unset, RBAC is disabled and all operations are permitted without credentials. |
-encrypt-at-rest | false | Enables AES-256-GCM encryption of values stored in the VLog. The key is loaded from the VELTRIXDB_ENCRYPTION_KEY environment variable (base64) or from -encryption-key-path. Startup fails fast if the key is missing or not exactly 32 bytes. |
-encryption-key-path | (empty) | Path to a file containing the 32-byte encryption key (raw or base64). Ignored if VELTRIXDB_ENCRYPTION_KEY is set in the environment. |
-audit-log | (empty) | Path to an append-only audit log (JSONL). Empty disables auditing. Covers PUT, DEL, and atomic ops; value bytes are never written to the audit log. |
-admin-token | (empty) | v1.1.0 Bearer token guarding every /admin/* endpoint on -metrics-addr. When unset, /admin/* accepts loopback connections only (non-loopback gets 403). When set, every /admin/* request — loopback included — must send Authorization: Bearer <token> or X-Admin-Token: <token> or it gets 401; comparison is constant-time. Also readable from the VELTRIX_ADMIN_TOKEN environment variable. /metrics, /healthz, and /readyz are never guarded. See Security. |
Admin API auth is separate from RBAC
-auth-config and -tls-* only protect the client data port (-addr / -tls-addr). The admin/metrics HTTP port (-metrics-addr, default :2112) is guarded separately: /admin/* is loopback-only by default, and -admin-token adds a bearer-token requirement for remote access — see Admin API Reference. Still keep the port behind a network policy on untrusted networks.
Cluster / Replication
Flags controlling deployment mode (standalone, raft, replicated), peer topology, and inter-node transport security.
| Flag | Default | Description |
|---|---|---|
-mode | standalone | Deployment mode: standalone | raft | replicated. standalone serves every request from local state (backward compatible, single node). raft commits writes through a Raft log (quorum-committed, linearizable writes; non-leaders return a MOVED <leader> redirect). replicated is primary-copy replication with per-request consistency via -consistency. |
-node-id | (empty) | Node ID for the cluster. Overrides the legacy -node flag when set (non-empty). |
-peers | (empty) | Comma-separated cluster peers: id@host:port,..., where host:port is each peer's client -addr. Every node in the cluster should be listed with the same set of peers. |
-seeds | (empty) | Comma-separated bootstrap seed nodes in nodeID=host:port form, used to seed the gossip/partition map at startup (self-entries are skipped automatically). |
-raft-addr | derived | Raft RPC listen address for this node. Empty derives host:(clientPort+2) from -addr. |
-repl-addr | derived | Replication server listen address. Empty derives host:(clientPort+1). |
-gossip-addr | derived | Gossip listener address. Empty derives host:(clientPort+3). |
-transfer-addr | derived | v1.1.0 Partition-transfer (rebalance) HTTP listen address. Empty derives host:(clientPort+5). Used by the TransferAgent to stream keys to their new owners after a ring change; honors the -cluster-tls-* / -cluster-mtls settings when set. |
-linearizable-reads | false | v1.1.0 Raft mode: serve GET through the ReadIndex fence (quorum-confirmed, never stale). Costs one heartbeat round-trip per read; followers redirect to the leader. Logged as a no-op warning outside -mode raft. |
-rack-id | (empty) | v1.1.0 This node's rack / availability-zone label (e.g. -rack-id=asia-south1-a). When set, partition placement and GetReplicasForKey never place two copies of a partition in the same failure domain — unless the replication factor exceeds the number of distinct racks, in which case placement falls back to distinct nodes while still spanning every rack available. Labels propagate to peers via gossip digests, so each node only needs its own flag. Reported as "rack" per node in the /admin/cluster topology JSON. Unset on all nodes keeps the previous deterministic round-robin placement. |
-auto-rebalance | true | v1.1.0 In distributed modes, automatically rebalance the partition ring and migrate keys to their new owners when nodes join, leave, or fail (3-second debounce per membership-event burst). Set -auto-rebalance=false to keep migration under manual control; the transfer listener still starts. |
-consistency | eventual | replicated-mode write consistency: eventual (ACK after the local write, async replication) | quorum (ACK after a majority of replicas apply the write) | strong (ACK after all replicas apply it). quorum/strong return a clear timeout/quorum-not-reached error when the required copies are unreachable. Ignored in standalone and raft modes. |
-cluster-tls-cert | (empty) | PEM certificate for inter-node (Raft/replication) TLS. |
-cluster-tls-key | (empty) | PEM key for inter-node TLS. |
-cluster-tls-ca | (empty) | PEM CA bundle for inter-node TLS peer verification. |
-cluster-mtls | false | Requires and verifies peer client certificates (mutual TLS) for inter-node Raft/replication traffic. |
For the semantics of each mode's consistency guarantees — and the remaining node-local caveats (replicated-mode secondary-index metadata; QUERY/RANGE/SCANCUR reads) now that namespace, hash-field, vector, and list/set writes route through the coordinator in all modes — see Deployment Modes.
Miscellaneous
| Flag | Default | Description |
|---|---|---|
-node | node-1 | See Network above — legacy node identifier, superseded by -node-id. |
All other operational surfaces (backup, restore, chaos testing, migration, load testing) are separate binaries documented in the CLI Reference, not cmd/server flags.
Production example: 8-disk Raft deployment
The following starts one node of a 3-node Raft cluster on an 8-NVMe-disk host, combining storage, durability, security, and cluster flags. Run the equivalent command on each of the three hosts, changing only -node-id and the bind address portion of -addr.
veltrixdb \
-mode raft \
-node-id n1 \
-addr 10.0.1.10:9000 \
-metrics-addr 10.0.1.10:2112 \
-peers n1@10.0.1.10:9000,n2@10.0.1.11:9000,n3@10.0.1.12:9000 \
-data-dirs /mnt/nvme0,/mnt/nvme1,/mnt/nvme2,/mnt/nvme3,/mnt/nvme4,/mnt/nvme5,/mnt/nvme6,/mnt/nvme7 \
-cache 65536 \
-wal-flush-window-ms 15 \
-vlog-flush-window-ms 15 \
-gc-threshold 0.30 \
-scrub-mb-per-sec 50 \
-encrypt-at-rest \
-encryption-key-path /etc/veltrixdb/encryption.key \
-tls-cert /etc/veltrixdb/tls/server.crt \
-tls-key /etc/veltrixdb/tls/server.key \
-auth-config /etc/veltrixdb/auth.json \
-audit-log /var/log/veltrixdb/audit.jsonl \
-cluster-tls-cert /etc/veltrixdb/cluster/node.crt \
-cluster-tls-key /etc/veltrixdb/cluster/node.key \
-cluster-tls-ca /etc/veltrixdb/cluster/ca.crt \
-cluster-mtls \
-archive-dir /mnt/wal-archive \
-archive-max-age-sec 604800Notes on this configuration: -cache 65536 allocates a 64 GB LIRS cache; -wal-flush-window-ms and -vlog-flush-window-ms are kept equal per the durability invariant; -cluster-mtls requires every peer to present a certificate signed by -cluster-tls-ca; and -archive-max-age-sec 604800 retains seven days of WAL archive for point-in-time recovery.