Broker configuration: serve.toml

Configuration layers, in ascending priority: defaults → the TOML file → ROXA_* environment variables → CLI flags. The file is passed with a flag: roxa serve -c serve.toml.

A full annotated example

# The gRPC data-plane address.
grpc_addr = "127.0.0.1:50051"

# The Kafka wire protocol address (kcat/librdkafka etc.). The --no-kafka flag disables it.
kafka_addr = "127.0.0.1:9092"

# The address the broker announces to Kafka clients (Metadata). For access from other
# machines this must be an address VISIBLE to the client (not 127.0.0.1).
# kafka_advertised_addr = "broker.example.com:9092"

# The data directory: WAL, metadata (embedded redb), segments (with backend = "fs").
data_dir = "data"

# The Prometheus /metrics address. Comment out or use --no-metrics to disable.
metrics_addr = "127.0.0.1:9644"

# The logging filter (overridden by the RUST_LOG environment variable).
log = "info"

# The license token (Pro/Enterprise). Without it — Community mode.
# More convenient to set via the ROXA_LICENSE env variable.
# license = "<token>"

# Data-plane authentication (gRPC + Kafka). Without this section — open access (for dev).
# gRPC clients present Basic credentials; Kafka clients — SASL/PLAIN.
# For production — only over TLS. Passwords are hashed with argon2.
# role: "admin" (everything) | "manager" (topics) | "writer" (write only) | "viewer" (read only).
# topics: a per-topic ACL for manager/writer/viewer — exact names or "prefix-*"; without the
# field — all topics. For a manager it also scopes topic management; it does not apply to admin
# (startup refused). Requires a Pro/Enterprise license (RBAC), otherwise startup is refused too.
# [[auth.users]]
# username = "service"
# password = "change-me"
# role = "admin"
# [[auth.users]]
# username = "orders-consumer"
# password = "change-me"
# role = "viewer"
# topics = ["orders-*"]        # Pro/Enterprise only

# Segment storage. The default is the local file system (zero-dep).
[storage]
backend = "fs"   # "fs" | "s3"

# S3/MinIO (backend = "s3"):
# [storage.s3]
# endpoint = "http://127.0.0.1:9000"
# bucket = "roxa"
# region = "us-east-1"
# access_key = "minioadmin"
# secret_key = "minioadmin"
# allow_http = true      # internal networks / MinIO without TLS only

Key fields

Field	Meaning	Default
grpc_addr	gRPC data-plane (roxactl, SDK)	127.0.0.1:50051
kafka_addr	Kafka wire protocol	127.0.0.1:9092
kafka_advertised_addr	the broker address in Metadata responses — critical for external access	= kafka_addr
data_dir	metadata and segments (fs)	data
metrics_addr	Prometheus /metrics	127.0.0.1:9644
[storage] backend	fs (local disk) or s3 (S3/MinIO)	fs
[[auth.users]]	data-plane users (Basic/SASL-PLAIN; admin/manager/writer/viewer roles, optional topics ACL in Pro/Ent)	none — open access
license / ROXA_LICENSE	the license token	none — Community

TLS for the gRPC/Kafka ports is configured in a separate section — see TLS and security.

Retention (per topic)

Data retention is set per topic at creation time — by size and/or by time; at least one segment is always kept:

roxactl topic create events --partitions 3 --retention-bytes 1073741824 --retention-ms 604800000

serve CLI flags

roxa serve [-c config.toml] [--addr H:P] [--kafka_addr H:P] [--data-dir DIR]
           [--metrics-addr H:P] [--no-metrics] [--no-kafka]