Security
VeltrixDB provides encryption at rest, TLS for client and inter-node traffic, a signed cluster secret for node-to-node requests, role-based access control, admin API access control, and a write audit log. This page covers how to enable each control and what it does and does not guarantee.
Encryption at rest
VeltrixDB encrypts stored values with AES-256-GCM. Encryption is off by default and is enabled per-node with a server flag:
veltrixdb -addr :9000 -data-dirs /mnt/nvme0,/mnt/nvme1 \
-encrypt-at-rest
The key itself is never passed on the command line. It is read at startup from the VELTRIXDB_ENCRYPTION_KEY environment variable (base64 of 32 bytes), or, if that is unset, from the file named by -encryption-key-path (raw or base64). Startup fails if the key is missing or not exactly 32 bytes:
export VELTRIXDB_ENCRYPTION_KEY=$(openssl rand 32 | base64)
veltrixdb -encrypt-at-rest -data-dirs /mnt/nvme0,/mnt/nvme1
kubectl veltrix migrate / POST /admin/migrate only rewrites records with an old schema version). Never swap the Secret under existing data. The only way to change the key is to copy the data through a client into a fresh node started with the new key — see Disaster Recovery.
CAS, INCR, DECR and SETNX persist the raw value without going through the compress → encrypt pipeline, so under -encrypt-at-rest those values are stored in plaintext, and on a cache miss they misread a value that was written (compressed or encrypted) by a normal PUT. On v1.13 and earlier, do not mix atomic ops with encryption at rest on the same keys. Fixed in v1.14 the atomic ops compress and encrypt like PUT and decode on a cache miss; values they wrote under an older build stay plaintext until their next update. Only values are encrypted; keys are stored in the clear.
On Kubernetes, supply the key through a Secret rather than a plain environment value baked into a manifest:
kubectl create secret generic veltrixdb-enc \
--from-literal=key=BASE64_32B
If the encryption key is missing at startup, nodes fail to open the VLog with an error resembling encryption: enabled but no key in VELTRIXDB_ENCRYPTION_KEY and no EncryptionKeyPath set. For HSM/KMS-backed key sourcing, mount the secret through a CSI driver (for example the AWS Secrets Manager CSI driver) so the raw key material is never stored in cluster state at rest.
TLS for client connections
The TCP data server can require TLS for client connections using a server certificate and key:
veltrixdb -addr :9000 -tls-addr :9443 \
-tls-cert /etc/veltrixdb/tls/server.crt \
-tls-key /etc/veltrixdb/tls/server.key
TLS is served on a separate listener, -tls-addr (default :9443), which runs alongside the plaintext listener on -addr; the plaintext port stays open, so firewall it if clients must use TLS. The listener requires TLS 1.3 (MinVersion is 1.3, so there is no TLS 1.2 fallback). Add -tls-ca to require client certificates signed by that CA.
Inter-node TLS and mutual TLS
Client-facing TLS and inter-node TLS are configured independently, because they usually terminate at different network boundaries. Use the -cluster-tls-* flags to secure Raft, replication and partition-transfer traffic between nodes (the transfer listener carries key migration and distributed search). The gossip listener (TCP, client port + 3) is not covered by these flags; keep it on a private network:
veltrixdb -mode raft -node-id n1 -addr 127.0.0.1:9000 \
-peers n1@127.0.0.1:9000,n2@127.0.0.1:9100,n3@127.0.0.1:9200 \
-cluster-tls-cert /etc/veltrixdb/tls/cluster.crt \
-cluster-tls-key /etc/veltrixdb/tls/cluster.key \
-cluster-tls-ca /etc/veltrixdb/tls/cluster-ca.crt \
-cluster-mtls
TLS turns on when both -cluster-tls-cert and -cluster-tls-key are set (TLS 1.3 minimum). The dialing node uses -cluster-tls-ca to verify the peer's server certificate. Client-certificate checking differs by listener:
- Replication and transfer listeners require and verify a peer client certificate only with
-cluster-mtls, which also needs-cluster-tls-ca(startup fails without it). - Raft RPC listener requires a client certificate whenever
-cluster-tls-cais set;-cluster-mtlsdoes not change it.
| Flag | Applies to | Effect |
|---|---|---|
-tls-cert / -tls-key / -tls-ca | Client TLS listener (-tls-addr) | TLS for application connections; -tls-ca requires client certificates |
-cluster-tls-cert / -cluster-tls-key / -cluster-tls-ca | Raft / replication / transfer listeners | TLS between nodes; the CA verifies peer server certificates (and, on Raft, client certificates) |
-cluster-mtls | Replication / transfer listeners | Requires and verifies peer client certificates (mutual TLS) |
-cluster-secret-file (or env VELTRIXDB_CLUSTER_SECRET) | Transfer listener | HMAC-SHA256 request signing — see below |
Cluster secret (HMAC request signing) New in v1.11
The transfer listener (client port + 5) accepts key writes from rebalancing (/transfer/keys) and serves distributed vector / text / hybrid search (/internal/search), so it is the cluster's trust boundary. Give every node the same shared secret, at least 16 bytes:
openssl rand -hex 32 > /etc/veltrixdb/cluster-secret
veltrixdb -mode raft ... -cluster-secret-file /etc/veltrixdb/cluster-secret
# or: export VELTRIXDB_CLUSTER_SECRET=... (used when the flag is empty)
Every request is then signed: X-Veltrix-Cluster-Time (Unix seconds) and X-Veltrix-Cluster-Auth = hex HMAC-SHA256 over time, method, path and body. The receiver rejects a missing or bad signature, or a timestamp more than 5 minutes from its own clock, with 401. /transfer/health is always exempt so load balancers need no key. A secret shorter than 16 bytes stops startup (cluster secret must be at least 16 bytes).
With neither a secret nor -cluster-mtls, the server starts but logs [transfer] WARNING: listener … is unauthenticated: anyone who can reach that port can write keys and run searches.
Role-based access control
Authentication and authorization are driven by a JSON config file passed via -auth-config. Each entry maps a username to a password hash and a role:
{
"users": [
{ "username": "alice", "password_hash": "pbkdf2$sha256$210000$<salt-b64>$<dk-b64>", "role": "admin" }
]
}
Hashes are generated with veltrix-admin hash-password — see Password hashing below for the hash format and the legacy-hash migration path.
Three built-in roles are supported:
| Role | Permissions |
|---|---|
admin | read + write + delete + admin (full access) |
readwrite | read + write + delete |
readonly | read only (GET, PING, INFO) |
Clients authenticate over the text protocol with:
AUTH alice secretpassword
OK
The binary protocol carries the same operation as command 0x09 with a length-prefixed username and password. Password hashes are compared with a constant-time comparison, and lookups against unknown usernames run a dummy constant-time comparison as well, to reduce user-enumeration via timing. When -auth-config is not supplied, authentication is disabled and every connection is granted full permissions — do not expose an unauthenticated data port to an untrusted network.
-net=cpp|uring|poll front-end does not implement AUTH, so the server refuses to start when it is combined with -auth-config (--net=cpp does not implement AUTH; run without --auth-config or use --net=go). TLS on -tls-addr stays on the Go server. Use the default -net=go for any deployment that needs RBAC.
Password hashing
Password hashes in the auth config use PBKDF2-HMAC-SHA256 with 210,000 iterations, a random per-user 16-byte salt, and a 32-byte derived key. The stored value is self-describing:
pbkdf2$sha256$<iterations>$<salt-base64>$<derived-key-base64>
Because the iteration count and salt are embedded in each hash, entries generated at different work factors verify correctly side by side. Generate a hash — together with a ready-to-paste auth config snippet — using the admin CLI:
veltrix-admin hash-password --user alice --password secret
Legacy hashes still work. The previous scheme — a bare 64-character hex digest of SHA-256(password + username) — is still verified for backward compatibility, so existing config files keep working. However, the server logs a deprecation warning for every legacy entry when the auth config is loaded. Re-hash those users with veltrix-admin hash-password and update the config file. Both schemes are compared in constant time.
veltrix-admin hash-password accepts a --legacy-sha256 flag that emits the old SHA-256(password + username) hash instead of PBKDF2. Use it only when a config must be consumed by a pre-upgrade server; new deployments should always use the default PBKDF2 output.
Admin API access control
As of v1.1.0 the /admin/* endpoints on the admin/metrics HTTP port (-metrics-addr, default :2112) are guarded. With no token configured, they accept loopback connections only — a request from any non-loopback address receives 403. To allow remote admin access, start the server with a bearer token:
veltrixdb -admin-token "$(openssl rand -hex 32)"
# or via the environment:
export VELTRIX_ADMIN_TOKEN=...
Once a token is set, every /admin/* request — including from loopback — must present it in either header, or it receives 401:
curl -H "Authorization: Bearer $VELTRIX_ADMIN_TOKEN" http://localhost:2112/admin/stats
curl -H "X-Admin-Token: $VELTRIX_ADMIN_TOKEN" http://localhost:2112/admin/stats
Token comparison is constant-time. /metrics, /healthz, and /readyz are deliberately not guarded, so Prometheus scrapes and Kubernetes probes work with no configuration. The repl-ship tool authenticates against a guarded source with --src-token (or VELTRIX_ADMIN_TOKEN) — see Replication & CDC.
-metrics-addr behind a network policy / firewall as before — the bearer token protects the admin surface, but the port also serves unauthenticated metrics and probe endpoints.
Audit log
VeltrixDB can append write records to a newline-delimited JSON (JSONL) file:
veltrixdb -audit-log /var/log/veltrixdb/audit.jsonl
Each line is a single JSON object:
{"ts":"2026-05-10T11:35:55.123456789Z","op":"PUT","key":"orders/4521","status":"ok"}
Fields: ts (RFC 3339 nanosecond UTC), op, key, ns (namespace, when distinct), status, and err when the status is an error. The record type also has an actor field, but nothing fills it in, so it never appears — the log carries no user identity. Value bytes are never logged.
What it covers (v1.12). Only single-key PUT and DEL calls into the storage engine (plus namespace PUTs rejected by a quota). Not recorded: batched writes (MPUT, pipelined PUTs the server coalesces into one batch, transactions, Raft's coalesced apply), atomic ops (CAS/INCR/DECR/SETNX), reads, admin API calls, and AUTH — successful and failed logins are not logged anywhere. (The server's flag help says "PUT, DEL, atomic ops"; the v1.12 code does not log atomic ops.)
Fixed in v1.14 one record per key for every engine write path: PUT / DEL from single-key writes, MPUT, coalesced pipelined PUTs, transaction commits and Raft batch apply, and the atomic ops under their own op (CAS, INCR, DECR, SETNX) with status ok, mismatch, not_found, exists or err — so atomic outcomes that wrote nothing are recorded too. Reads, admin calls, AUTH and TTL expiry are still not recorded, and the engine drains and fsyncs the audit log on shutdown.
Audit writes are asynchronous: records are enqueued to a bounded channel (8192 by default) and a background goroutine appends them with periodic fsync. Auditing never blocks the data plane — when the channel is full the record is dropped and audit_dropped_total in /admin/stats increments. Alert on it.
PUT/DEL), carries no actor, and drops records under back-pressure. If a control needs user identity or a hash-chained trail, record identity outside VeltrixDB and ship the log to a write-once backend (S3 Object Lock, a WORM-mounted volume).
Backups and PITR archives hold plaintext
With -encrypt-at-rest, values are encrypted in the VLog, but the continuous WAL archive written to -archive-dir holds decrypted (plaintext) values. Protect the archive location (and anything it is copied to) with the same controls as the data itself: filesystem permissions, encrypted volumes or bucket-side encryption, and restricted access. A full or incremental backup copies the VLog bytes as stored (encrypted values stay encrypted), so it is only readable with the same key.
Container image
The official Dockerfile builds on a gcr.io/distroless/cc-debian12 runtime base (no shell or package manager; the cc variant carries the C/C++ runtime libraries the cgo build needs). The image is built with CGO_ENABLED=1 for the native index; pass --build-arg CGO_ENABLED=0 for a static pure-Go image.
Compliance posture
VeltrixDB ships a control mapping document (docs/SOC2_CONTROLS.md) that maps its built-in capabilities — encryption at rest, RBAC, mTLS, the audit log, Prometheus-based monitoring, and backup/restore — to SOC 2 Trust Service Criteria (CC6.x, CC7.x, CC8.1, A1.x, C1.x, PI1.x).
The control-mapping document also lists gaps to disclose to an auditor rather than paper over: the audit log is not hash-chained, covers only engine writes (on v1.13 and earlier only PUT/DEL; every write path since v1.14), carries no user identity and drops records under back-pressure; logins (AUTH) are not logged; at-rest encryption applies to whole values (no per-field encryption, keys in the clear); the master key comes from an environment variable or key file, with no KMS/HSM integration and no key rotation; and there is no PII detection or redaction scanner. Mitigations: external immutable log storage with identity recorded outside VeltrixDB, application-layer field encryption, CSI-based KMS secret injection, and external DLP scanning. The govulncheck CI job is non-blocking, so its findings must be triaged by hand.
Operators preparing for an audit should be able to produce, at minimum: proof the encryption secret exists (/admin/version shows "encryption_enabled": true), the current auth-config user/role list plus a client transcript of a rejected command before AUTH (the server does not log logins), a TLS/mTLS handshake trace, recent backup manifests, a sample of the shipped audit log with audit_dropped_total, and Grafana/alert history. See Monitoring & Observability for the metrics and alerting side of that evidence set.