Configuration

The server reads a single TOML file. A copy of core/server/config.toml is embedded into the binary and serves as the default configuration, so the server boots with working defaults even without any file on disk. The embedded file is commented throughout and is the authoritative reference for the exact version you're running.

A config file doesn't have to be complete. It is merged over the embedded defaults, so a minimal file overrides only what it names:

[system]
path = "/var/lib/iggy"

[tcp]
address = "0.0.0.0:8090"

[http]
address = "0.0.0.0:3000"

How configuration loads

Configuration is resolved in three layers. Later layers win:

1. Embedded defaults: the config.toml compiled into the binary.
2. Config file: the path in IGGY_CONFIG_PATH, or core/server/config.toml resolved against the current working directory. A missing file is only a warning. The server continues on embedded defaults.
3. Environment variables: any IGGY_-prefixed override.

Before the environment is read, the server loads a .env file from the working directory, or from the path named by IGGY_ENV_PATH.

After boot the server writes the effective configuration, including the addresses it actually bound, to {system.path}/runtime/current_config.toml.

Environment variables

Every configuration key can be overridden with an IGGY_ variable. The name is the TOML path, uppercased, with dots turned into underscores:

IGGY_TCP_ADDRESS=0.0.0.0:8090          # [tcp] address
IGGY_HTTP_ENABLED=true                 # [http] enabled
IGGY_SYSTEM_PATH=/var/lib/iggy         # [system] path
IGGY_SYSTEM_LOGGING_LEVEL=debug        # [system.logging] level
IGGY_SYSTEM_SHARDING_CPU_ALLOCATION=4  # [system.sharding] cpu_allocation

Two variables live outside the config schema: IGGY_ROOT_USERNAME and IGGY_ROOT_PASSWORD set the root credentials, always as a pair. Only the first creation of the root user reads them. On an existing data directory the stored root user is recovered unchanged.

Secrets

Five values are secret-flagged: http.jwt.encoding_secret, http.jwt.decoding_secret, system.encryption.key, cluster.auth.shared_secret, and cluster.auth.previous_shared_secret. Prefer setting them through their environment variables (IGGY_HTTP_JWT_ENCODING_SECRET, IGGY_SYSTEM_ENCRYPTION_KEY, IGGY_CLUSTER_AUTH_SHARED_SECRET, and so on) instead of storing them in a file. Secret values are masked in logs and never serialized into runtime/current_config.toml.

Validation at boot

• Unknown keys are silently ignored. A typo in a key name leaves the default in force, so check spelling when a setting doesn't seem to take effect. The relocated keys below are the exception: they refuse boot.
• system.segment.archive_expired = true and system.recovery.recreate_missing_state = true are unsupported placeholders. Setting either aborts boot.
• Several sections validate relationships between keys (QUIC windows, sharding shutdown budgets, metadata journal sizing, partition transfer floors). A violation aborts boot with an error naming the keys. The constraints are listed with their sections below.
• The RUST_LOG environment variable always takes precedence over system.logging.level.

Command-line flags

iggy-server accepts exactly three flags:

Relocated configuration keys

Retention, durability, and segment layout are no longer server-wide settings. They became per-topic options set at topic creation. See Topic options. The server refuses to boot while any of the old keys is still present, in the config file or in the environment, and the error names the replacement. This is deliberate: the storage knobs are create-only options now, so a topic created while an old key was silently ignored could never be given the setting afterwards.

Other sections from older configs ([message_saver], [system.state], [system.backup], [system.compression], [tcp.socket], segment cache_indexes, and similar) were removed without a boot check. Like any unknown key they're silently ignored. Remove them from your file.

Reference

The tables below list every section with its shipped defaults. In cluster mode, every enabled transport takes its port from this node's cluster.nodes ports entry. The transport's own address picks only the bind interface.

[http]

HTTP sessions hold live server-side session state (they count against metadata.clients_table_max). Consumer group management (create, get, delete) is available over HTTP. Group membership (join, leave) is not and needs a stateful transport.

In cluster mode, followers forward control-plane requests (streams, topics, users, and so on) to the current primary when a cluster-wide JWT key exists (see [http.jwt] below). Forwarding does not cover the partition plane: message produce and consumer-offset writes must reach the partition's primary node directly, while message polls read locally on any node.

[http.cors]

[http.jwt]

There is no default secret. With the secrets left empty, each server start mints a random signing key, so issued tokens do not survive a restart and are valid only on the node that issued them. If you configure a secret, set it through the environment (IGGY_HTTP_JWT_ENCODING_SECRET / IGGY_HTTP_JWT_DECODING_SECRET), never commit it, and use a long random value.

In cluster mode the secret has an extra role: a configured secret, identical on every node, makes bearer tokens valid cluster-wide and activates follower-to-primary HTTP forwarding. With cluster.auth enabled the JWT key is instead derived from the cluster PSK. Without either, tokens are node-local and forwarding stays disabled.

[[http.jwt.trusted_issuers]]

Opt-in trust of external token issuers for application-to-application authentication. With none configured, the listener accepts only self-issued HS256 tokens.

[[http.jwt.trusted_issuers]]
issuer = "https://issuer.example.com"
audience = "iggy.apache.org"
jwks_url = "https://issuer.example.com/.well-known/jwks.json"
user_id = 1

issuer, audience, and jwks_url are required per entry. user_id is the non-zero iggy user every token from that issuer is remapped onto. It defaults to 0 (root), which is rejected, so set it explicitly.

Enabling an issuer opens an outbound JWKS fetch that is reachable before a token's signature is verified: a token naming the issuer with an unknown key id can trigger a fetch to jwks_url. The target is fixed (not attacker-chosen), concurrent misses coalesce onto one fetch, and repeats are rate-limited to one outbound request per issuer per short window. The same window bounds how quickly a freshly rotated signing key is picked up.

[http.metrics]

The metrics route requires authentication like every other read: a missing or invalid bearer credential is rejected with 401. Any authenticated user may scrape. There's no extra RBAC rule. Scrapers present a JWT or a personal access token as the bearer:

scrape_configs:
  - job_name: "iggy"
    metrics_path: "/metrics"
    authorization:
      type: Bearer
      credentials: "<personal-access-token>"
    static_configs:
      - targets: ["localhost:3000"]

[http.tls]

HTTP TLS is file-based only. There's no self_signed option for this listener. Both files must exist when enabled.

[tcp]

TCP is the highest-throughput transport. These two keys, plus the TLS block below, are the entire section.

[tcp.tls]

[quic]

Raising max_concurrent_bidi_streams is a transport decision only: the server's accept loop takes one stream at a time and waits for its reply before accepting the next, so a higher cap does not make command handling concurrent.

[quic.certificate]

[websocket]

The size knobs are optional. Leaving one unset keeps the compio-ws (tungstenite) default shown in parentheses. A malformed size string fails config load.

[websocket.tls]

TLS across transports

The self_signed flag doesn't mean the same thing everywhere:

Ephemeral certificates change on every start and are meant for loopback development, not production.

[system]

Storage sub-paths chain relative to each other: [system.runtime] path = "runtime" (runtime data, including current_config.toml), [system.logging] path = "logs", [system.stream] path = "streams", [system.topic] path = "topics" (relative to the stream path), [system.partition] path = "partitions" (relative to the topic path).

[system.logging]

[system.encryption]

[system.partition]

Durability and flush cadence (enforce_fsync, messages_required_to_save, size_of_messages_required_to_save) are per-topic creation options. See Topic options.

[system.segment] and [system.recovery]

Segment size and preallocation are per-topic creation options (segment_size, preallocate_segments).

[system.memory_pool]

The pool has 28 buckets with buffer sizes from 4 KiB to 512 MiB.

[data_maintenance.messages]

[heartbeat]

When enabled, a connection that sends nothing (no request, no PING) for 1.2 x interval (36 s at the default) and still holds a consumer group membership has its session released, so its groups rebalance off it. A connection holding no membership is left alone and reaped when its socket closes.

The Rust, Go, Python, Node, and async Java SDKs ping automatically every 5 s, well inside the staleness window, but only from a connected high-level client: the Rust and async Java pingers are armed by connect(), so a session that logs in without it never pings. The blocking Java and C# SDKs have no automatic heartbeat, only a manual ping. Wherever nothing pings, an idle consumer group member is evicted, and only the application can keep it alive (ping) or bring it back (reconnect).

[telemetry]

[system.sharding]

Valid cpu_allocation syntaxes:

• "all": one shard per available CPU core
• a number, e.g. 4: four shards pinned to cores 0 to 3
• a range, e.g. "5..8": three shards on cores 5, 6, 7
• "numa:auto": all NUMA nodes and cores, NUMA-aware
• "numa:nodes=0,1;cores=4;no_ht=true": NUMA nodes 0 and 1, four cores each, no hyperthreads

[metadata]

Tunables for the metadata consensus plane (shard 0's VSR replica: users, streams, topics, sessions).

[partition]

Per-partition consensus plane tunables. Unlike [metadata] (one plane on shard 0), a pipeline exists per partition, so raising these multiplies pinned memory by the partition count.

[message_bus]

Tunables for the internal bus that ships consensus traffic between replicas and client traffic between shards.

[personal_access_token]

[consumer_group]

[cluster]

Cluster mode is configured here but documented in Clustering. The section contains:

Durations are rounded down to the consensus 10 ms tick. Values under 10 ms become one tick.

Sub-sections:

• [cluster.auth]: replica-to-replica authentication (PSK plus BLAKE3 keyed-MAC handshake). shared_secret must be at least 32 bytes of CSPRNG output, identical on every node. Prefer IGGY_CLUSTER_AUTH_SHARED_SECRET. previous_shared_secret enables rolling key rotation.
• [cluster.tls]: TLS 1.3 on the replica port. Requires cluster.auth.enabled. The PSK authenticates the peer, TLS supplies confidentiality.
• [[cluster.nodes]]: the full roster, byte-identical on every node. Each entry has name, ip, replica_id, and ports (tcp, quic, http, websocket, tcp_replica). In cluster mode ports is the single source of listener ports: every enabled transport needs an explicit per-node port or the server refuses to start. advertised_address and per-CIDR advertised_addresses selectors control what clients are told to dial.