VeltrixDB Docs
v1.16 GitHub FAQ Quickstart

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
Key rotation is not implemented. The engine loads exactly one key at startup and records no per-record key version, so values written under the old key cannot be decrypted once the key is replaced, and no command re-encrypts in place (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.
v1.13 and earlier: atomic ops bypass encryption and compression. On v1.13 and earlier, 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:

FlagApplies toEffect
-tls-cert / -tls-key / -tls-caClient TLS listener (-tls-addr)TLS for application connections; -tls-ca requires client certificates
-cluster-tls-cert / -cluster-tls-key / -cluster-tls-caRaft / replication / transfer listenersTLS between nodes; the CA verifies peer server certificates (and, on Raft, client certificates)
-cluster-mtlsReplication / transfer listenersRequires and verifies peer client certificates (mutual TLS)
-cluster-secret-file (or env VELTRIXDB_CLUSTER_SECRET)Transfer listenerHMAC-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:

RolePermissions
adminread + write + delete + admin (full access)
readwriteread + write + delete
readonlyread 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.

The C++ network front-end has no AUTH New in v1.7 The experimental -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.
Loading an auth config with zero users is rejected. VeltrixDB refuses to enable auth enforcement from an empty user list, to avoid silently locking out (or silently permitting) every connection.

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.

Emitting the deprecated format. 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.

The token is a second layer, not a substitute for isolation. On untrusted networks, keep -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.

The audit log is neither complete nor tamper-evident. It is plain local JSONL (not hash-chained), covers only engine writes (on v1.13 and earlier only single-key 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).

This is a control mapping, not a certification. VeltrixDB's own documentation is explicit that a SOC 2 attestation is a property of your operating environment, not of the database alone. The project provides the technical capabilities an auditor will look for; it does not claim SOC 2 certification for VeltrixDB itself, and there is no attestation report to hand to an auditor out of the box.

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.