Configuration Reference

FerricStore is configured through Elixir's standard config/config.exs (compile-time) and config/runtime.exs (runtime). Some parameters can also be changed at runtime via the CONFIG SET Redis command.

Mode applicability. Each option is tagged with its scope:

• Both — applies to standalone and embedded mode
• Standalone only — ignored in embedded mode (no TCP listener, no connections)
• Embedded only — only relevant when running as an in-process library

Mode

config :ferricstore, :mode, :embedded

Network

Standalone only — these options are ignored in embedded mode.

The TCP listener also sets the following socket options (not configurable at runtime):

config :ferricstore, :port, 6379
config :ferricstore, :health_port, 4000

Storage

See Architecture Guide — Three-Tier Storage for how ETS, Bitcask, and mmap work together.

config :ferricstore, :data_dir, "data"
config :ferricstore, :shard_count, 0  # 0 = auto-detect from CPU cores
config :ferricstore, :hot_cache_max_value_size, 65_536

Supervisor

# Production default: 20 restarts in 10 seconds
config :ferricstore, :supervisor_max_restarts, {20, 10}

# Test config: generous budget for shard-kill tests
config :ferricstore, :supervisor_max_restarts, {1000, 60}

Memory Management

Eviction: How It Works

See Architecture Guide — LFU Eviction and Architecture Guide — Memory Guard for implementation details.

Defaults out of the box:

Setting	Default	Meaning
:max_memory_bytes	nil (no limit)	Eviction is disabled until you set this. Without a limit, ETS grows unbounded.
:eviction_policy	:volatile_lru	When eviction triggers, only keys with a TTL are candidates. Least-frequently-accessed go first.
:lfu_decay_time	1 minute	Counter decays by 1 every minute — keys that stop being accessed lose priority within minutes.
:lfu_log_factor	10	Moderate increment curve. Matches Redis default.
:memory_guard_interval_ms	100 ms	Memory checked 10 times per second.

If you set nothing, eviction never happens and RAM grows until the OS kills the process. At minimum, set :max_memory_bytes in production.

FerricStore has a three-tier storage model:

                 ┌─────────────────────────┐
  Tier 1 (HOT)  │  ETS (RAM)              │  ~1-5 us reads
                 │  key → value in memory  │
                 └────────────┬────────────┘
                              │ eviction moves value
                              │ out of RAM (key stays)
                 ┌────────────▼────────────┐
  Tier 2 (COLD) │  ETS (RAM) metadata     │  ~50-200 us reads
                 │  key → nil (disk loc)   │  (pread from disk)
                 └────────────┬────────────┘
                              │ always persisted
                 ┌────────────▼────────────┐
  Tier 3 (DISK) │  Bitcask (append-only)  │  source of truth
                 │  all keys, all values   │
                 └─────────────────────────┘

Eviction does NOT delete data. When a key is evicted, its value is removed from RAM (Tier 1 → Tier 2) but it stays on disk. The ETS entry keeps the key and disk location (file_id, offset) so the next read can fetch it. The key goes from "hot" (~1-5 us) to "cold" (~50-200 us) — slower but still accessible.

Expiration DOES delete data. When a key's TTL expires, the key is permanently removed from both ETS and Bitcask (a tombstone is written to disk). The key is gone — GET returns nil, EXISTS returns 0. This happens two ways: lazy deletion on the next read, and active sweep every 100ms (configurable). This is the same behavior as Redis EXPIRE.

When RAM usage reaches max_memory_bytes, MemoryGuard must choose which hot keys to make cold. This involves two things:

1. LFU scoring — a counter on each key that tracks how often it's accessed
2. Eviction policy — a filter that decides which keys are eligible

They are not separate systems — they work together:

  RAM full → MemoryGuard triggers
         │
         ▼
  ┌──────────────────────────┐
  │  1. FILTER by policy     │  ← eviction policy controls this
  │     volatile_lru: only   │
  │       keys with TTL      │
  │     allkeys_lru: all     │
  │       keys               │
  │     volatile_ttl: only   │
  │       keys with TTL      │
  │     noeviction: nobody   │
  │       (reject writes)    │
  └────────────┬─────────────┘
               ▼
  ┌──────────────────────────┐
  │  2. SORT by score        │  ← LFU counter controls this
  │     volatile_lru: lowest │    (except volatile_ttl which
  │       LFU score first    │     sorts by shortest TTL)
  │     allkeys_lru: lowest  │
  │       LFU score first    │
  │     volatile_ttl: shortest│
  │       remaining TTL first│
  └────────────┬─────────────┘
               ▼
  ┌──────────────────────────┐
  │  3. EVICT                │
  │     Set value to nil in  │
  │     ETS. Key stays, disk │
  │     location preserved.  │
  └──────────────────────────┘

Eviction Policies

Quick decision guide:

• "I have cache data (with TTL) and permanent data (no TTL)" → :volatile_lru
• "Everything is cache data" or "I don't use TTLs" → :allkeys_lru
• "Short-lived keys should go first" → :volatile_ttl
• "My data fits in RAM, never evict" → :noeviction

If you're unsure, use :volatile_lru (the default). Set a TTL on cache entries and leave permanent data without TTL.

LFU Scoring (the counter behind volatile_lru and allkeys_lru)

Every key in ETS has an LFU counter — a packed 24-bit integer stored in the 7-tuple alongside the key and value. This counter answers: "how important is this key based on recent access patterns?"

  ┌─────────────────────────────────────┐
  │  24-bit LFU counter                 │
  │  ┌──────────────┬──────────────┐    │
  │  │ ldt (16 bit) │ counter (8b) │    │
  │  │ last decay   │ log access   │    │
  │  │ timestamp    │ frequency    │    │
  │  └──────────────┴──────────────┘    │
  └─────────────────────────────────────┘

How it works:

1. On every read (GET, HGET, etc.), the counter is probabilistically incremented. "Probabilistically" means: the higher the counter already is, the harder it is to increment. A key accessed 1 million times won't have a much higher counter than one accessed 10,000 times — this prevents popular keys from monopolizing RAM forever.

2. Over time, the counter decays. Every :lfu_decay_time minutes (default: 1), the counter drops by 1. A key that was hot an hour ago but hasn't been accessed since will have a low score — even if it had millions of historical accesses. This is what makes it adaptive: access patterns change, and the counter follows.

3. On eviction, MemoryGuard compares the effective counter (after applying time decay) across candidate keys. The key with the lowest score gets evicted first.

The two LFU config knobs:

config :ferricstore, :lfu_decay_time, 1
config :ferricstore, :lfu_log_factor, 10

These match Redis's lfu-decay-time and lfu-log-factor exactly — same algorithm, same defaults, same behavior.

Memory Pressure Thresholds

MemoryGuard monitors ETS memory at configurable intervals and takes action at three pressure levels. All thresholds are relative to max_memory_bytes:

If max_memory_bytes is not set, MemoryGuard is disabled and no eviction or rejection occurs. This is fine for development but not recommended for production — an unbounded ETS can eventually exhaust system RAM.

config :ferricstore, :max_memory_bytes, 4_294_967_296  # 4 GB
config :ferricstore, :eviction_policy, :allkeys_lru
config :ferricstore, :memory_guard_interval_ms, 100

Raft Consensus & Durability

See Architecture Guide — Raft Consensus for the full write path, state machine internals, and batcher design.

# Default durability for all namespaces (overridden per-namespace)
# :quorum = crash-safe (default), :async = fire-and-forget (faster)
config :ferricstore, :default_durability, :quorum

Raft controls write durability — whether a write is crash-safe before the client gets an OK response. It is not about read consistency (reads always come from ETS which is updated immediately regardless of Raft).

What Raft does

Every write follows this path:

  Client writes SET key value
         │
         ▼
  ETS updated immediately        ← reads see the new value NOW
         │
         ▼
  Batcher accumulates writes     ← groups writes for throughput
         │
         ▼
  ra (Raft library) commits      ← blocks until quorum confirms
         │                          (single node = self-quorum)
         ▼
  v2_append_batch + fsync        ← persisted to disk
         │
         ▼
  Client gets OK                 ← crash-safe at this point

If the node crashes after ETS update but before Raft commit, the write is lost. This window is typically <1ms (the group-commit batch interval).

Two durability modes (per-namespace)

Within Raft-enabled mode, each key namespace (prefix before the first :) can be configured with a different durability level:

Default: All namespaces use :quorum with a 1ms group-commit window. This can be changed globally via config :ferricstore, :default_durability, :async to make all namespaces default to async (Redis-like speed). Per-namespace overrides via FERRICSTORE.CONFIG SET or :namespace_config still take precedence over the global default.

When to use :async: For data you can afford to lose on crash — ephemeral counters, rate limit windows, analytics events, cache warming. The 10-100x latency reduction is significant for high-throughput fire-and-forget workloads.

When to use :quorum: For anything that must survive a crash — user data, sessions, financial transactions, queue state. This is the default and the right choice for most data.

Note: Async durability mode with values >64KB may exhibit read-back issues. Use quorum mode for large values.

How Raft log replication works (multi-node)

In a multi-node cluster, one node is the leader and the others are followers. All writes go to the leader.

  Client: SET key value
         │
         ▼
  Leader node
    1. Appends write to its local Raft log
    2. Sends AppendEntries RPC to all followers (in parallel)
    3. Followers write to their local Raft log and acknowledge
    4. Once majority (2 of 3) have acknowledged → committed
    5. Leader replies OK to client
    6. Leader applies the write (ETS + Bitcask)
    7. Followers apply the write on their side

Replication happens continuously as writes arrive — the leader streams new log entries to followers, piggybacked on heartbeats (every ~100-500ms). There is no separate "replication phase."

If a follower is down or slow, it misses some entries. When it comes back online, the leader detects the gap and sends all missing entries in bulk. The follower replays them in order and catches up. This is automatic — no manual intervention needed.

Single-node mode (the common case): the leader is its own quorum. Writes are committed as soon as they're fsynced locally. No network round-trips.

Configure per-namespace at runtime:

# Session data: quorum durability, 1ms batch window (default)
redis-cli FERRICSTORE.CONFIG SET session window_ms 1 durability quorum

# Analytics counters: async durability, 5ms batch window (fast, lossy)
redis-cli FERRICSTORE.CONFIG SET analytics window_ms 5 durability async

# Reset to defaults
redis-cli FERRICSTORE.CONFIG RESET analytics

Or in Elixir config:

config :ferricstore, :namespace_config, %{
  "session" => %{window_ms: 1, durability: :quorum},
  "analytics" => %{window_ms: 5, durability: :async}
}

Connection Limits

Safety limits that prevent a single connection from consuming unbounded memory. These protect against oversized payloads, slow-drip buffer attacks, and runaway transactions or pipelines.

Max value size

Applied at two levels:

1. RESP3 parser — when a bulk string header $N\r\n declares a length exceeding the limit, the parser returns an error immediately without reading the body. The connection receives -ERR value too large (N bytes, max M bytes) and is closed.
2. Embedded API — FerricStore.set/3 checks byte_size(value) before writing and returns {:error, "ERR value too large ..."} if the value exceeds the limit.

# Allow values up to 10 MB (capped at 64 MB hard limit)
config :ferricstore, :max_value_size, 10_485_760

Buffer, MULTI queue, and pipeline limits

These are compile-time module attributes in FerricstoreServer.Connection and cannot be changed at runtime. The defaults are generous enough for any legitimate workload while preventing pathological resource exhaustion:

• Buffer overflow — a client sending incomplete RESP frames faster than they can be parsed will accumulate data in the receive buffer. At 128 MB the connection is closed with -ERR connection buffer overflow.
• MULTI queue overflow — a client queueing more than 100K commands inside MULTI triggers an automatic DISCARD with -ERR MULTI queue overflow.
• Pipeline overflow — a pipeline batch with more than 100K commands is rejected with -ERR pipeline batch too large.

Sendfile Zero-Copy

Standalone only — embedded mode returns values directly via ETS or v2_pread_at, with no socket involved.

config :ferricstore_server, :sendfile_threshold, 65_536

TLS

Standalone only — embedded mode has no network listener so TLS does not apply.

See Security Guide — TLS for certificate setup and mutual TLS configuration.

config :ferricstore, :tls_port, 6380
config :ferricstore, :tls_cert_file, "/etc/ssl/ferricstore/cert.pem"
config :ferricstore, :tls_key_file, "/etc/ssl/ferricstore/key.pem"
config :ferricstore, :tls_ca_cert_file, "/etc/ssl/ferricstore/ca.pem"
config :ferricstore, :require_tls, true

Merge / Compaction

See Architecture Guide — Merge / Compaction for the compaction lifecycle, semaphore, and file selection.

Bitcask files are append-only and accumulate dead entries over time. The merge scheduler periodically compacts data files by copying live entries to new files and discarding the old ones.

config :ferricstore, :merge,
  check_interval_ms: 60_000,
  fragmentation_threshold: 0.5

Expiry Sweep

When you set a TTL on a key (SET key value EX 60 or FerricStore.set("key", "value", ttl: 60_000)), the key doesn't disappear the instant it expires. FerricStore uses two complementary strategies to clean up expired keys — just like Redis:

1. Lazy expiry (on read): When any command reads a key, it checks expire_at_ms. If the key is past its TTL, it's deleted on the spot and the command returns as if the key doesn't exist. This is free — it piggybacks on the read that was happening anyway. Hot keys are always cleaned up instantly.

2. Active expiry sweep (background): Every :expiry_sweep_interval_ms (default: 1 second), each shard samples keys from ETS and deletes any that have expired. This catches keys that nobody is reading — without the sweep, a key set with a 5-minute TTL that nobody ever reads again would sit in ETS and on disk forever, wasting RAM.

  Lazy expiry (on read):              Active sweep (background):

  GET key                             Every 1 second per shard:
    │                                   │
    ▼                                   ▼
  Check expire_at_ms                  Sample keys from ETS
    │                                   │
    ├─ not expired → return value       ├─ expired → delete from ETS
    │                                   │             + write tombstone to disk
    └─ expired → delete + return nil    └─ not expired → skip

Tuning guidance:

The sweep also writes tombstones to Bitcask for expired keys, so they're cleaned from disk on the next compaction cycle.

See Architecture Guide — Recovery for how expired keys are handled during shard restart.

config :ferricstore, :expiry_sweep_interval_ms, 1_000

Sync Flush

FerricStore has two disk write modes that work together:

Async flush (normal writes): During regular operation, writes accumulate in a pending list and are flushed to disk periodically via v2_append_batch_nosync (page cache only, ~1us). A separate async fsync is then submitted to Tokio to make the data durable. This async fsync runs in the background — the shard GenServer continues processing commands while the disk syncs.

Sync flush (durability-critical operations): Certain operations need to guarantee that ALL pending data is on disk before they can proceed. These include: DEL (tombstone must be durable), KEYS/SCAN (must reflect latest state), shutdown (must not lose data), and any explicit flush request. For these, the shard calls flush_pending_sync which:

1. Writes all pending entries to disk via v2_append_batch (includes fsync)
2. If an async fsync is already in-flight from a previous batch, waits for it to complete before proceeding

The sync_flush_timeout_ms controls step 2 — how long the shard GenServer will block waiting for an in-flight async fsync to finish. If the timeout expires (disk is very slow, I/O stall), the shard logs an error and proceeds anyway to avoid permanently blocking the GenServer.

  Normal write path (async):

  pending list → v2_append_batch_nosync → page cache
                                            │
                                            └─ v2_fsync_async → Tokio → disk
                                                (background, non-blocking)

  Durability-critical path (sync):

  flush_pending_sync
    │
    ├─ 1. Write pending → v2_append_batch (includes fsync)
    │
    └─ 2. If async fsync in-flight from previous batch:
           wait up to sync_flush_timeout_ms for it to complete
           │
           ├─ completed → proceed (data is durable)
           └─ timeout → log error, proceed anyway (avoid GenServer deadlock)

Tuning guidance:

If this timeout fires in production, it means your disk can't keep up with write throughput. Check: I/O utilization (iostat), disk queue depth, whether the filesystem journal is creating write amplification. Consider fewer shards or faster storage.

See Architecture Guide — Write Path for the full write pipeline and how async/sync flushes interact with Raft group commit.

config :ferricstore, :sync_flush_timeout_ms, 5_000

Large Value Warning

config :ferricstore, :embedded_large_value_warning_bytes, 512 * 1024

Node Discovery (libcluster)

FerricStore uses libcluster for automatic node discovery in multi-node deployments.

# Local development: Gossip (multicast)
config :libcluster,
  topologies: [
    ferricstore: [
      strategy: Cluster.Strategy.Gossip,
      config: [
        port: 45892,
        if_addr: "0.0.0.0",
        multicast_addr: "230.1.1.251"
      ]
    ]
  ]

# Kubernetes: DNS
config :libcluster,
  topologies: [
    ferricstore: [
      strategy: Cluster.Strategy.Kubernetes.DNS,
      config: [
        service: "ferricstore-headless",
        application_name: "ferricstore"
      ]
    ]
  ]

# Disable (tests, single-node)
config :libcluster, topologies: :disabled

Example: Development Configuration

# config/dev.exs
config :ferricstore, :port, 6379
config :ferricstore, :data_dir, "data"
config :ferricstore, :max_memory_bytes, 1_073_741_824  # 1 GB
config :ferricstore, :eviction_policy, :volatile_lru

config :libcluster,
  topologies: [
    ferricstore: [
      strategy: Cluster.Strategy.Gossip
    ]
  ]

Example: Test Configuration

# config/test.exs
config :ferricstore, :port, 0
config :ferricstore, :health_port, 0
config :ferricstore, :data_dir, System.tmp_dir!() <> "/ferricstore_test_#{:os.getpid()}"
config :ferricstore, :shard_count, 4
config :ferricstore, :sync_flush_timeout_ms, 1_000
config :ferricstore, :max_memory_bytes, 1_073_741_824
config :ferricstore, :eviction_policy, :volatile_lru
config :ferricstore, :memory_guard_interval_ms, 5_000
config :ferricstore, :merge, check_interval_ms: 600_000, fragmentation_threshold: 0.99
config :ferricstore, :expiry_sweep_interval_ms, 600_000
config :ferricstore, :read_sample_rate, 1

# Generous supervisor budget for shard-kill tests
config :ferricstore, :supervisor_max_restarts, {1000, 60}

config :libcluster, topologies: :disabled

Example: Production Configuration

# config/runtime.exs
config :ferricstore, :port, String.to_integer(System.get_env("FERRICSTORE_PORT", "6379"))
config :ferricstore, :data_dir, System.get_env("FERRICSTORE_DATA_DIR", "/var/lib/ferricstore")
config :ferricstore, :max_memory_bytes, 8_589_934_592  # 8 GB
config :ferricstore, :eviction_policy, :allkeys_lru

config :ferricstore, :tls_port, 6380
config :ferricstore, :tls_cert_file, System.get_env("TLS_CERT_FILE")
config :ferricstore, :tls_key_file, System.get_env("TLS_KEY_FILE")
config :ferricstore, :require_tls, true

config :libcluster,
  topologies: [
    ferricstore: [
      strategy: Cluster.Strategy.Kubernetes.DNS,
      config: [
        service: "ferricstore-headless",
        application_name: "ferricstore"
      ]
    ]
  ]

Runtime Environment Variables

These environment variables are read from config/runtime.exs in production (MIX_ENV=prod). They configure FerricStore when running as a release or Docker container.

Core

Durability

Memory & Eviction

LFU Scoring

Expiry

Slow Log

Security

TLS

Connection

Raft Internals

Clustering

Supervisor (advanced)

Runtime Configuration (CONFIG SET)

Some parameters can be changed at runtime without restarting FerricStore. This works in both standalone and embedded mode — same parameters, same behavior, different API.

Standalone mode (Redis protocol)

redis-cli CONFIG SET maxmemory-policy allkeys-lru
redis-cli CONFIG GET maxmemory
redis-cli CONFIG GET *             # get all parameters

Embedded mode (Elixir API)

# Set a parameter
:ok = Ferricstore.Config.set("maxmemory-policy", "allkeys-lru")

# Get a single parameter (fast ETS read, ~100ns)
"allkeys-lru" = Ferricstore.Config.get_value("maxmemory-policy")

# Get parameters matching a pattern (returns list of {key, value} pairs)
pairs = Ferricstore.Config.get("*")            # all parameters
pairs = Ferricstore.Config.get("maxmemory*")   # matching pattern

# Read-only parameter
{:error, "ERR Unsupported CONFIG parameter: maxmemory (read-only)"} =
  Ferricstore.Config.set("maxmemory", "999")

Changes take effect immediately. A [:ferricstore, :config, :changed] telemetry event is emitted on every successful CONFIG SET.

Read-Write Parameters

Read-Only Parameters (CONFIG GET only)

These reflect the startup configuration and cannot be changed at runtime.

Namespace-Specific Configuration

FerricStore supports per-namespace tuning for group commit windows and durability modes. The namespace is derived from the key prefix (everything before the first :).

Standalone mode:

# Session keys: quorum durability, 1ms batch window
redis-cli FERRICSTORE.CONFIG SET session window_ms 1 durability quorum

# Analytics counters: async durability, 5ms batch window
redis-cli FERRICSTORE.CONFIG SET analytics window_ms 5 durability async

# Reset to defaults
redis-cli FERRICSTORE.CONFIG RESET analytics

Embedded mode:

# Same thing via Elixir — call the Config command handler directly
alias Ferricstore.Commands.Server

# Set namespace config (builds a store map for the handler)
Server.handle("FERRICSTORE.CONFIG", ["SET", "session", "window_ms", "1", "durability", "quorum"], %{})
Server.handle("FERRICSTORE.CONFIG", ["SET", "analytics", "window_ms", "5", "durability", "async"], %{})

# Reset
Server.handle("FERRICSTORE.CONFIG", ["RESET", "analytics"], %{})

See Raft Consensus & Durability for what :quorum vs :async durability means, and the Architecture Guide for how namespace-aware group commit works.