Configuration Reference#
mudud reads its configuration from a TOML file. The file controls listen ports, execution mode, storage paths, and io_uring behavior.
File location#
An explicit --cfg / -c path is used exclusively: a missing or invalid file fails without fallback. Without that option, the server tries ./mudud.cfg, then ~/.mududb/mudud.cfg; if neither exists it returns NotFound. Relative storage paths are resolved from the server process working directory.
Generate a default config#
mudud init-cfg
Configuration fields#
The table lists generated configuration values and defaults for optional fields. mpk_path, db_path, listen_ip, http_listen_port, pg_listen_port, and enable_async are required in a hand-written TOML file; the parser does not fill them in. mudud init-cfg writes ./mudud.cfg and overwrites an existing file.
Field |
Type |
Default |
Description |
|---|---|---|---|
|
string |
|
Path to the application package directory. |
|
string |
|
Path to the database directory. |
|
string |
|
IP address to listen on. |
|
u16 |
|
HTTP management API port. |
|
usize |
|
HTTP worker thread count. |
|
u16 |
|
PostgreSQL wire protocol port (Legacy only). |
|
string |
|
Wasm component ABI target. Allowed: |
|
boolean |
|
Enable the WASI component runtime. |
|
string |
|
|
|
u16 |
|
TCP framed protocol port. |
|
boolean |
|
One TCP listener per worker. |
|
usize |
|
Worker thread count. |
|
u32 |
|
io_uring completion queue depth. |
|
boolean |
|
Enable io_uring accept multishot. |
|
boolean |
|
Enable io_uring recv multishot. |
|
boolean |
|
Enable io_uring fixed buffers. |
|
boolean |
|
Enable io_uring fixed files. |
|
string |
|
|
|
u64 |
|
io_uring log chunk size in bytes. |
|
usize |
|
Database page size in bytes. Persistent: changing it for an existing database requires migration or re-initialization. |
|
u64 |
|
Group-commit batching window in microseconds: how long a queued WAL commit batch may age before the flush driver flushes it. |
|
string |
|
WAL durability mode: |
|
u64 |
|
WAL fsync interval in milliseconds for |
Server and routing modes#
server_mode: controls the backend I/O/runtime path.Legacy: traditional blocking I/O path for maximum compatibility.IOUring: Linux io_uring based high-performance async I/O.Tokio: Tokio-based async runtime.
routing_mode: controls how requests are routed to workers.ConnectionId(default): route based on connection identifier.PlayerId: route based on an application-level player/user identifier.RemoteHash: hash-based routing using remote address or hashed key.
Procedure resource limits#
The optional [invocation_limits] table caps WASM procedure execution. Omitted fields use the defaults below; changes require a restart. Every value must be positive, memory_bytes must not exceed total_memory_bytes, and max_concurrent_per_app must not exceed max_concurrent. Unknown fields in this table are rejected.
Field |
Type |
Default |
Description |
|---|---|---|---|
|
usize |
|
Total linear-memory bytes across all memories in one invocation. |
|
u64 |
|
Wasm instruction fuel, including component initialization. |
|
u64 |
|
Wall-clock execution budget in milliseconds, including transaction setup. |
|
usize |
|
Maximum encoded procedure or host-call input size. |
|
usize |
|
Maximum encoded procedure or host-call output size. |
|
u64 |
|
Maximum host calls, including resource-opening calls. |
|
usize |
|
Maximum simultaneously open worker sessions and file handles. |
|
usize |
|
Maximum total table elements in one invocation. |
|
usize |
|
Process-wide maximum admitted procedure calls. |
|
usize |
|
Maximum admitted calls sharing an application name. |
|
usize |
|
Process-wide reserved guest linear-memory budget. |
Replication#
The optional [replication] table configures primary-replica streaming replication or Raft fault tolerance. When absent, the server runs as a single node. Replication currently requires server_mode = "Tokio"; Legacy and IOUring reject it at startup. Exactly one of the [replication.stream] / [replication.raft] subsections must be present — the present subsection selects the mode.
Field |
Type |
Default |
Description |
|---|---|---|---|
|
u64 |
required |
Identifier of this node. Persisted to |
|
u16 |
required |
Port the replication and Raft channel listens on; must not collide with |
|
u64 |
|
Flow-control window of the replication stream, in segments. |
|
u64 |
|
Committed WAL bytes beyond the last snapshot that trigger the next per-worker snapshot. Must be greater than zero. |
|
u64 |
|
Interval between WAL/staging GC watermark evaluations, in seconds. Must be greater than zero. |
[replication.stream] — primary-replica streaming replication without Raft:
Field |
Type |
Default |
Description |
|---|---|---|---|
|
boolean |
required |
Whether this node is the configured primary; exactly one cluster member sets |
|
boolean |
required |
Whether the primary waits for a replica’s durable ack before answering a commit. |
|
u64 |
|
Synchronous replication wait timeout in milliseconds. |
[replication.raft] — Raft consensus fault tolerance:
Field |
Type |
Default |
Description |
|---|---|---|---|
|
u64 |
|
Raft state machine tick interval in milliseconds. |
|
u64 |
|
Raft election timeout in ticks. |
Cluster members are listed as [[replication.peers]] entries with node_id, host, and port. The peer list must be non-empty, contain no duplicate node ids or addresses, and include this node’s own node_id. Stream mode requires at least two peers.
Backup#
The optional [backup] table configures base backups and WAL archiving. When absent, the server runs backup-free: WAL prefix GC reclaims chunks without archiving them. See Backup and Restore for the backup workflow.
Field |
Type |
Default |
Description |
|---|---|---|---|
|
string |
unset |
Directory base backups are written to; required by the |
|
string |
unset |
Directory sealed WAL chunks are continuously archived to. |
|
string |
|
|
Example mudud.cfg#
mpk_path = "./mpk"
db_path = "./data"
listen_ip = "127.0.0.1"
http_listen_port = 8300
http_worker_threads = 1
pg_listen_port = 5432
tcp_listen_port = 9527
server_mode = "Tokio"
worker_threads = 0
io_uring_ring_entries = 1024
io_uring_accept_multishot = true
io_uring_recv_multishot = true
io_uring_enable_fixed_buffers = false
io_uring_enable_fixed_files = false
routing_mode = "ConnectionId"
enable_async = true
tcp_multi_port = false
log_chunk_size = 67108864
page_size = 4096
See the Server Configuration Contract for compatibility and upgrade rules.
WAL archiving from [backup] is wired into the Tokio backend’s worker configuration. The current IOUring startup path does not pass that configuration to workers: its base-backup and logical-dump management endpoints do not imply continuous WAL archiving. Use Tokio for the documented archive/PITR workflow. archive_mode = "always" currently does not gate commit acknowledgements on archive durability.
See Replication and Raft Fault Tolerance for complete cluster examples and Server Management for listeners by mode.