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

# 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"

# 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

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

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

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