Configuration

Settings merge in this order: built-in defaults, a TOML file, RUVIO_* environment variables, then CLI flags. Later layers win. Unknown TOML fields fail startup. With no --config, the process loads RUVIO_CONFIG, then ruvio.toml beside the binary, then /etc/ruvio/ruvio.toml, then ./ruvio.toml. A missing file is created from the built-in defaults. Environment variables and CLI flags are written back into that file at startup. The file is read once: an edit applies on the next start. There is no CONFIG SET. After start, CONFIG GET * (or a glob) shows the effective process and redacts requirepass. ruvio --help lists CLI names. This page follows docs/CONFIGURATION.md.

Sample file

address = "127.0.0.1:6379"
shards = 1
advertised_host = "127.0.0.1"
# advertised_port = 6379
hot_keys = []
notify_keyspace_events = ""
shutdown_grace_ms = 30000
metrics_address = "127.0.0.1:9121"

[protocol]
max_arguments = 64
max_key_bytes = 1048576
max_value_bytes = 16777216
max_command_bytes = 67108864
max_pipeline_commands = 1024
max_connection_buffer_bytes = 67108864
databases = 16

[timeouts]
idle_ms = 300000
read_ms = 30000
write_ms = 30000

[connections]
max_global = 10000
max_per_ip = 256
max_per_user = 0
max_commands_per_second = 0

[requests]
max_queued_requests = 1024
max_output_buffer_bytes = 16777216

[persistence]
profile = "memory"
data_dir = "./data"
wal_segment_bytes = 268435456
sync_interval_ms = 1000
snapshot_max_bytes = 1073741824
snapshot_journal_bytes = 67108864
snapshot_interval_ms = 60000
snapshot_min_mutations = 0

[replication]
role = "off"
listen = "127.0.0.1:26379"
primary = "127.0.0.1:26379"

[security]
requirepass = ""
protected_mode = true
tls_cert = ""
tls_key = ""

[[security.users]]
name = "app"
rules = "on >app-secret ~app:* +@read +ping +auth +info"

[memory]
max_shard_bytes = 0
max_process_bytes = 0
reserved_headroom_bytes = 16777216
maxmemory_policy = "noeviction"
maxmemory_samples = 16
active_expire_keys = 16
hash_max_compact_entries = 64
hash_max_compact_value_bytes = 64

[scripts]
max_bytes = 16384
max_cached = 1024
max_calls = 1024
max_instructions = 1000000

How to apply

Save the sample as TOML, then point the process at it with --config. Environment and flags still override that file. A typical split: put stable limits and ACL users in the file; put the bind address, password, shard count, and advertise host in the environment so the same file works on a laptop and in Docker.

Installed binary (cargo install ruvio)

The crate puts ruvio and ruvio-ctl on the host. Paths in the file are relative to the working directory, not the binary.

ruvio --config ./ruvio.toml

Override one field without editing the file. CLI wins:

ruvio --config ./ruvio.toml --durability always --data-dir ./data

Or skip the file and use environment names (RUVIO_ADDR, RUVIO_SHARDS, RUVIO_DURABILITY, RUVIO_DATA_DIR, RUVIO_REQUIREPASS, RUVIO_ADVERTISE_HOST, …):

RUVIO_SHARDS=2 RUVIO_ADDR=0.0.0.0:6379 ruvio

From a checkout

Pass flags after -- so Cargo does not eat them.

cargo run --release --bin ruvio -- --config ./ruvio.toml
RUVIO_SHARDS=4 RUVIO_ADDR=0.0.0.0:6379 cargo run --release --bin ruvio

Linux container

The published image already sets environment that the file would otherwise default differently:

• RUVIO_ADDR=0.0.0.0:6379
• RUVIO_DATA_DIR=/data
• RUVIO_PROTECTED_MODE=false

Those values beat a file unless you pass a later CLI flag. The process is UID 10001. The entrypoint is ruvio, so extra arguments are flags, not a shell.

Environment only — no file:

docker run --rm -p 6379:6379 -v ruvio-data:/data \
  -e RUVIO_DURABILITY=everysec \
  -e RUVIO_REQUIREPASS=secret \
  salihcantekin/ruvio:linux

Two shards that remote clients can follow. Advertise the host (and published ports) the app can reach:

docker run --rm -p 6379-6380:6379-6380 -v ruvio-data:/data \
  -e RUVIO_SHARDS=2 \
  -e RUVIO_ADVERTISE_HOST=YOUR_SERVER_IP \
  -e RUVIO_PROTECTED_MODE=false \
  salihcantekin/ruvio:linux

Same sample file, mounted where the process can read it. Keep data_dir = "/data" (or omit it and keep the image default). Host paths such as ./data are wrong inside the container.

docker run --rm -p 6379:6379 \
  -v ruvio-data:/data \
  -v "$PWD/ruvio.toml:/etc/ruvio.toml:ro" \
  salihcantekin/ruvio:linux --config /etc/ruvio.toml

Then -e RUVIO_SHARDS=2 still overrides shards in that file. Put a password on any bind that is not loopback when you leave protected_mode false.

Coupled settings

These pairs are validated together. A mismatch fails before a listener opens.

Process

Listening for expired and evicted keys

notify_keyspace_events is empty by default. Its value combines channel type and event classes:

• K enables keyspace channels named __keyspace@<db>__:<key>; payload is the event name.
• E enables keyevent channels named __keyevent@<db>__:<event>; payload is the key name.
• g means delete, $ means string SET, x means expired, and e means evicted. A enables all four event classes.

To publish both expiration and eviction keyevent notices, combine E with x and e:

notify_keyspace_events = "Exe"

Ruvio reads this setting at startup; restart after changing the TOML file. Subscribe to the exact channel for the key's database, such as SSUBSCRIBE __keyevent@0__:expired or SSUBSCRIBE __keyevent@0__:evicted. PSUBSCRIBE patterns do not receive these notifications. Expired and evicted keyevent messages contain only the key name as their payload; they do not include or return the key's value.

await db.SubscribeExpiredAsync(message =>
    Console.WriteLine($"Expired key: {message.Payload}"));
await db.SubscribeEvictedAsync(message =>
    Console.WriteLine($"Evicted key: {message.Payload}"));

Notices are live and best-effort: they are not replayed to later subscribers and are not written to the WAL. An eviction notice is sent only when memory pressure triggers eviction; the default noeviction policy does not evict. In a multi-shard deployment, notifications are local to the shard that owns the key; one subscription does not collect events from every shard. The Operator Pub/Sub screen also provides expired/evicted listeners with database and shard selection.

Protocol

Timeouts

Zero is rejected for all three.

Connections

Requests

Persistence

Replication

Security

The operator UI does not have its own accounts. Sign-in is AUTH against this list. Empty user and password send no AUTH and the session is default. default is always present: on nopass ~* +@all until requirepass is set, and then that password belongs to default. Named users in [[security.users]] are loaded at startup and survive a restart. ACL SETUSER from the UI changes only the running process.

Memory

Scripts

Zero is rejected. Environment names: RUVIO_SCRIPT_MAX_BYTES, RUVIO_SCRIPT_MAX_CACHED, RUVIO_SCRIPT_MAX_CALLS, RUVIO_SCRIPT_MAX_INSTRUCTIONS.