Configuration#
A node reads conf/candybox.properties. Every key can be overridden by an environment variable
named CANDYBOX_<KEY> (dots become underscores, upper-cased) — for example
CANDYBOX_ZOOKEEPER_CONNECT — and the environment value wins. This makes it easy to ship one image
and configure each instance through the environment.
Common keys#
| Key | Meaning | Default |
|---|---|---|
node.id | Cluster-unique node id. Falls back to the trailing number in $HOSTNAME (so a Kubernetes pod candybox-2 becomes node 2). | — |
zookeeper.connect | ZooKeeper connect string, shared by BookKeeper and Candybox coordination. | 127.0.0.1:2181 |
server.bind | Address clients connect to. | 0.0.0.0:9709 |
server.advertised | Address published to the cluster for routing (set to a reachable hostname). | bind address |
health.port | HTTP port for /healthz (liveness), /readyz (503 while ZooKeeper is unreachable), /metrics. | 9710 |
server.io.threads | Netty event loops framing client traffic. 0 uses Netty’s default (twice the available processors). | 0 |
server.handler.threads | Threads running the request handler, off the event loops. Each connection is pinned to one of them. | max(32, cores × 4) |
server.max.inflight.per.connection | Requests one connection may have queued for the handler before the node stops reading from it. | 8 |
server.drain.timeout.millis | How long a shutdown lets in-flight requests finish before their connections are cut. | 10000 |
quorum.* | BookKeeper replication per ledger role (E/Qw/Qa). | 3/3/2 (WAL, manifest), 3/2/2 (data) |
compaction.interval.millis | Background maintenance tick: compaction, ledger GC, rename-intent finalize, and the multipart and locator-relay sweeps. 0 disables it. | 15000 (15 s) |
multipart.upload.ttl.millis | How long an abandoned multipart upload is kept before a background sweep aborts it. | 7 days |
zero.copy.relay.budget.bytes | Cross-partition copy/rename: bytes of locator relays one node may have pending in ZooKeeper before it answers BUSY. | 33554432 (32 MiB) |
rename.intent.abandon.millis | Cross-partition rename: age after which an unclaimed preparation can be CAS-aborted (source stays live); also the unclaimed locator relay expiry age. Claimed transfers retain their intent and byte pins until committed completion or a fenced destination recovery proves abort. | 60000 (60 s) |
Full reference#
The complete, commented list of keys lives in
candybox.properties.example,
and the CandyboxConfig section of
OPERATIONS.md
documents the operational meaning of each tunable, including the security, consistency, and garbage
collection settings.