Skip to main content

Configuration

rstmdb is configured through a YAML file and environment variables.

Configuration Loading​

Priority (highest to lowest):

  1. Environment variables
  2. Configuration file
  3. Default values

Specify config file path:

RSTMDB_CONFIG=/etc/rstmdb/config.yaml rstmdb

Full Configuration Reference​

# Network settings
network:
  # Address to bind to
  bind_addr: "127.0.0.1:7401"

  # Connection idle timeout in seconds
  idle_timeout_secs: 300

  # Maximum concurrent connections
  max_connections: 1000

# Storage settings
storage:
  # Data directory for WAL and snapshots
  data_dir: "./data"

  # WAL segment size in megabytes
  wal_segment_size_mb: 64

  # Fsync policy for durability
  # Options: every_write, never, {every_n: N}, {every_ms: N}
  fsync_policy: every_write

  # Maximum versions per machine (0 = unlimited)
  max_machine_versions: 0

  # Allow re-creating instances after deletion with the same ID
  allow_instance_recreate: true

  # Allow the FLUSH_ALL operation to clear all data (disabled by default).
  # Must be false when replication is enabled — FLUSH_ALL does not replicate and
  # would diverge the cluster, so the server refuses to start with both set.
  allow_flush_all: false

# Authentication settings
auth:
  # Require authentication
  required: false

  # SHA-256 hashes of valid tokens
  token_hashes:
    - "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"

  # External file containing token hashes (one per line)
  secrets_file: "/etc/rstmdb/tokens"

# TLS settings
tls:
  # Enable TLS
  enabled: false

  # Server certificate path
  cert_path: "/etc/rstmdb/server.pem"

  # Server private key path
  key_path: "/etc/rstmdb/server-key.pem"

  # Require client certificates (mTLS)
  require_client_cert: false

  # CA certificate for client verification
  client_ca_path: "/etc/rstmdb/client-ca.pem"

# Replication settings (omit or use role: standalone for a single-node server)
replication:
  # Role: standalone (default), primary, or replica
  role: standalone

  # Mode: async (default) or sync (primary waits for replica ACKs)
  mode: async

  # Replica only: host:port of the primary
  # upstream: "primary.internal:7401"

  # Sync mode (primary): min ACKs required, timeout
  sync_replicas: 1
  sync_timeout_ms: 5000

  # Alerting thresholds
  max_lag_entries: 10000
  max_lag_seconds: 30

  # Auth (primary): SHA-256 hashed tokens — rstmdb-cli hash-token <token>
  # auth_token_hashes:
  #   - "ec46c1b607eb52e1db74a115a1ec14a872b19f47909a5ce1d57a651d7d7b116c"
  # auth_secrets_file: "/etc/rstmdb/replication-tokens"

  # Auth (replica): plaintext token to present to the primary
  # auth_token: "my-replica-token"

  # Tuning
  poll_interval_ms: 10
  heartbeat_interval_secs: 5
  reconnect_delay_secs: 1
  reconnect_max_delay_secs: 60
  lag_check_interval_secs: 10

  # TLS (replica → primary)
  tls_enabled: false
  # tls_ca_path: "/etc/rstmdb/ca.pem"
  # tls_insecure: false

# Automatic compaction settings
compaction:
  # Enable automatic compaction
  enabled: true

  # Compact after this many events
  events_threshold: 10000

  # Compact when WAL exceeds this size (MB)
  size_threshold_mb: 100

  # Minimum seconds between compactions
  min_interval_secs: 60

# Metrics settings
metrics:
  # Enable Prometheus metrics endpoint
  enabled: true

  # Metrics endpoint bind address
  bind_addr: "0.0.0.0:9090"

# Logging settings
logging:
  # Log level: trace, debug, info, warn, error
  level: "info"

  # Log format: json, pretty
  format: "json"

Environment Variables​

All configuration options can be set via environment variables:

Network​

VariableConfig PathDefault
RSTMDB_BINDnetwork.bind_addr127.0.0.1:7401
RSTMDB_IDLE_TIMEOUTnetwork.idle_timeout_secs300
RSTMDB_MAX_CONNECTIONSnetwork.max_connections1000

Storage​

VariableConfig PathDefault
RSTMDB_DATAstorage.data_dir./data
RSTMDB_WAL_SEGMENT_SIZE_MBstorage.wal_segment_size_mb64
RSTMDB_FSYNC_POLICYstorage.fsync_policyevery_write
RSTMDB_MAX_MACHINE_VERSIONSstorage.max_machine_versions0
RSTMDB_ALLOW_INSTANCE_RECREATEstorage.allow_instance_recreatetrue
RSTMDB_ALLOW_FLUSH_ALLstorage.allow_flush_allfalse

Authentication​

VariableConfig PathDefault
RSTMDB_AUTH_REQUIREDauth.requiredfalse
RSTMDB_AUTH_TOKEN_HASHauth.token_hashes[0]None
RSTMDB_AUTH_SECRETS_FILEauth.secrets_fileNone

TLS​

VariableConfig PathDefault
RSTMDB_TLS_ENABLEDtls.enabledfalse
RSTMDB_TLS_CERTtls.cert_pathNone
RSTMDB_TLS_KEYtls.key_pathNone
RSTMDB_TLS_CLIENT_CAtls.client_ca_pathNone
RSTMDB_TLS_REQUIRE_CLIENT_CERTtls.require_client_certfalse

Compaction​

VariableConfig PathDefault
RSTMDB_COMPACT_ENABLEDcompaction.enabledtrue
RSTMDB_COMPACT_EVENTScompaction.events_threshold10000
RSTMDB_COMPACT_SIZE_MBcompaction.size_threshold_mb100
RSTMDB_COMPACT_INTERVALcompaction.min_interval_secs60

Replication​

See Replication for how the pieces fit together.

VariableConfig PathDefault
RSTMDB_REPL_ROLEreplication.rolestandalone
RSTMDB_REPL_MODEreplication.modeasync
RSTMDB_REPL_UPSTREAMreplication.upstreamNone
RSTMDB_REPL_SYNC_REPLICASreplication.sync_replicas1
RSTMDB_REPL_SYNC_TIMEOUT_MSreplication.sync_timeout_ms5000
RSTMDB_REPL_AUTH_TOKENreplication.auth_tokenNone
RSTMDB_REPL_AUTH_TOKEN_HASHappends to replication.auth_token_hashesNone
RSTMDB_REPL_AUTH_SECRETS_FILEreplication.auth_secrets_fileNone
RSTMDB_REPL_POLL_INTERVAL_MSreplication.poll_interval_ms10
RSTMDB_REPL_HEARTBEAT_INTERVAL_SECSreplication.heartbeat_interval_secs5
RSTMDB_REPL_RECONNECT_DELAY_SECSreplication.reconnect_delay_secs1
RSTMDB_REPL_RECONNECT_MAX_DELAY_SECSreplication.reconnect_max_delay_secs60
RSTMDB_REPL_LAG_CHECK_INTERVAL_SECSreplication.lag_check_interval_secs10
RSTMDB_REPL_TLS_ENABLEDreplication.tls_enabledfalse
RSTMDB_REPL_TLS_CAreplication.tls_ca_pathNone
RSTMDB_REPL_TLS_INSECUREreplication.tls_insecurefalse

Metrics​

VariableConfig PathDefault
RSTMDB_METRICS_ENABLEDmetrics.enabledtrue
RSTMDB_METRICS_BINDmetrics.bind_addr0.0.0.0:9090

Logging​

VariableConfig PathDefault
RUST_LOGlogging.levelinfo
RSTMDB_LOG_FORMATlogging.formatjson

Fsync Policies​

every_write (Default)​

Safest option. Every write is synced to disk before acknowledgment.

storage:
  fsync_policy: every_write

Durability: No data loss on crash Performance: Slowest

every_n​

Sync after every N writes.

storage:
  fsync_policy:
    every_n: 100

Durability: Up to N-1 writes at risk Performance: Balanced

every_ms​

Sync at most every N milliseconds.

storage:
  fsync_policy:
    every_ms: 100

Durability: Up to N ms of writes at risk Performance: Balanced

never​

Never explicitly sync. Relies on OS buffering.

storage:
  fsync_policy: never

Durability: All unsynced data at risk Performance: Fastest

Authentication Setup​

Generate Token Hash​

rstmdb-cli hash-token my-secret-token
# 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

Configure Server​

auth:
  required: true
  token_hashes:
    - "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"

Or via environment:

export RSTMDB_AUTH_REQUIRED=true
export RSTMDB_AUTH_TOKEN_HASH=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

Using Secrets File​

# /etc/rstmdb/tokens (one hash per line)
9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
a5f3c6c86f1a6d3b8c4e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1
auth:
  required: true
  secrets_file: "/etc/rstmdb/tokens"

TLS Setup​

Generate Certificates​

# Generate CA
openssl genrsa -out ca-key.pem 4096
openssl req -new -x509 -days 365 -key ca-key.pem -out ca.pem -subj "/CN=rstmdb-ca"

# Generate server certificate
openssl genrsa -out server-key.pem 4096
openssl req -new -key server-key.pem -out server.csr -subj "/CN=localhost"
openssl x509 -req -days 365 -in server.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server.pem

Configure TLS​

tls:
  enabled: true
  cert_path: "/etc/rstmdb/server.pem"
  key_path: "/etc/rstmdb/server-key.pem"

mTLS (Mutual TLS)​

tls:
  enabled: true
  cert_path: "/etc/rstmdb/server.pem"
  key_path: "/etc/rstmdb/server-key.pem"
  require_client_cert: true
  client_ca_path: "/etc/rstmdb/client-ca.pem"

Example Configurations​

Development​

network:
  bind_addr: "127.0.0.1:7401"

storage:
  data_dir: "./data"
  fsync_policy: never  # Fast for development
  allow_flush_all: true  # Useful for dev reset

auth:
  required: false

metrics:
  enabled: false

Production​

network:
  bind_addr: "0.0.0.0:7401"
  idle_timeout_secs: 300
  max_connections: 5000

storage:
  data_dir: "/var/lib/rstmdb"
  wal_segment_size_mb: 128
  fsync_policy: every_write

auth:
  required: true
  secrets_file: "/etc/rstmdb/tokens"

tls:
  enabled: true
  cert_path: "/etc/rstmdb/server.pem"
  key_path: "/etc/rstmdb/server-key.pem"

compaction:
  enabled: true
  events_threshold: 100000
  size_threshold_mb: 1000
  min_interval_secs: 300

metrics:
  enabled: true
  bind_addr: "0.0.0.0:9090"

logging:
  level: "info"
  format: "json"

High Throughput​

storage:
  fsync_policy:
    every_ms: 100
  wal_segment_size_mb: 256

compaction:
  events_threshold: 500000
  size_threshold_mb: 5000