A node reads its whole configuration from environment variables when it starts. There is no
configuration file and nothing to keep in sync between a file and the process: change a variable and
restart the node. A single node needs none of them to run, and a cluster needs a handful
(QUEEN_RAFT_REPLICATOR=openraft, QUEEN_RAFT_NODE_ID, QUEEN_RAFT_PEERS), which
cluster walks through. Everything else is here for when you want to change a
default, with the value the code applies when you don’t.
docker run -p 6632:6632 -v queen-data:/var/lib/queen/raft \
-e QUEEN_KV_MAX_VALUE_BYTES=262144 -e LOG_LEVEL=info \
ghcr.io/queen-mq/queen:2.9.0In a cluster, give every node the same values except the per-node ones: QUEEN_RAFT_NODE_ID,
QUEEN_RAFT_LISTEN, QUEEN_SERVER_ID and, with the Kafka facade, QUEEN_KAFKA_ADVERTISED_ADDR.
Broker
The table below is generated from server/src/config.rs and the files named in its header. The
booleans it lists accept true/false, 1/0, yes/no and on/off; unset or empty takes
the default, and any other value stops the node at boot with the variable’s name.
The broker is configured entirely through environment variables: 120 of them, listed below with the defaults the code actually applies. Booleans go through one strict parser: an unparseable value is a fatal boot error, while unset and empty both fall back to the default.
Also read as is an older name for the same setting: either name configures the same thing, and the row’s name wins when both are set.
Server
| Variable | Type | Default | Also read as |
|---|---|---|---|
PORT |
string | 6632 |
|
QUEEN_BIND_ADDR |
string | 0.0.0.0 |
|
QUEEN_MAX_BODY_BYTES |
integer | 67108864 (64 MiB) |
|
QUEEN_SERVER_ID |
string | HOSTNAME, else a random queen-<hex> name |
Key/value state, timers and the sweeper
| Variable | Type | Default | Also read as |
|---|---|---|---|
QUEEN_KV_MAX_KEYS_PER_CALL |
integer | 1024 |
|
QUEEN_KV_MAX_OPS_PER_CALL |
integer | 256 |
|
QUEEN_KV_MAX_TENANTS |
integer | 10_000 |
|
QUEEN_KV_MAX_VALUE_BYTES |
integer | 65536 (64 KiB) |
|
QUEEN_KV_QUOTA_HOT_PERCENT |
integer | 80 |
|
QUEEN_KV_QUOTA_RELEASE_PERCENT |
integer | 90 |
|
QUEEN_KV_READ_BURST |
integer | 400 |
|
QUEEN_KV_READ_RATE |
integer | 200 |
|
QUEEN_KV_REQUIRE_GRANT |
boolean | the value of QUEEN_TENANCY_HEADER (so: false) |
|
QUEEN_KV_TRUSTED_PROXY |
boolean | false |
|
QUEEN_KV_TXN_WRITE_BURST |
integer | 20_000 |
|
QUEEN_KV_TXN_WRITE_RATE |
integer | 10_000 |
|
QUEEN_KV_WRITE_BURST |
integer | 200 |
|
QUEEN_KV_WRITE_RATE |
integer | 100 |
|
QUEEN_RAFT_KV_SWEEP_LIMIT |
integer | 512 |
|
QUEEN_RAFT_KV_SWEEP_MS |
integer | 1000 |
|
QUEEN_RAFT_TIMER_FIRE_BATCH |
integer | 256 |
|
QUEEN_RAFT_TIMER_FIRE_MAX_BYTES |
integer | 4194304 (4 MiB) |
|
QUEEN_RAFT_TIMER_TICK_MS |
integer | 50 (0: timers never fire) |
|
QUEEN_STMT_TIMEOUT_MS |
integer | 30000 |
|
QUEEN_STREAMS_MAX_STATE_BYTES |
integer | 16777216 (16 MiB) |
|
QUEEN_SWEEPER_BACKOFF_MAX_MS |
integer | 60000 |
|
QUEEN_SWEEPER_BACKOFF_MIN_MS |
integer | 1000 |
|
QUEEN_SWEEPER_MAX_ATTEMPTS |
integer | 5 |
|
QUEEN_SWEEPER_TRANSIENT_BACKOFF_MS |
integer | 1000 |
|
QUEEN_TIMERS_MAX_HORIZON_S |
integer | 7776000 (90 days) |
|
QUEEN_TIMERS_MAX_OPS_PER_CALL |
integer | 256 |
Retention and background jobs
| Variable | Type | Default | Also read as |
|---|---|---|---|
METRICS_FLUSH_MS |
integer | 60000 (at least 1000) |
|
PARTITION_CLEANUP_DAYS |
integer | 30 |
|
PARTITION_CLEANUP_SECONDS |
integer | (empty): PARTITION_CLEANUP_DAYS applies |
|
QUEEN_DASH_MAX_QUEUE_ROWS |
integer | 500000 |
|
QUEEN_DASH_NODE_RETENTION_H |
integer | 168 |
|
QUEEN_DASH_QUEUE_RETENTION_H |
integer | 24 |
|
QUEEN_METRICS_GROUP_LAG_MAX_CURSORS |
integer | 200000 (0 turns the consumer group lag gauges off) |
|
QUEEN_PARTITION_CLEANUP_ENABLED |
boolean | true |
|
QUEEN_RAFT_RETENTION_VISIT |
integer | 8192 |
|
QUEEN_RAFT_ROWS_WINDOW |
boolean | true |
|
QUEEN_RAFT_TRACE_RETENTION_S |
integer | 604800 (7 days) |
|
QUEEN_RAFT_TXN_WINDOW_MIN_S |
integer | 900 |
|
RETENTION_BATCH_SIZE |
integer | 1000 |
|
RETENTION_INTERVAL |
integer | 5000 |
Storage and replication
| Variable | Type | Default | Also read as |
|---|---|---|---|
QUEEN_QLOG_DIRX |
boolean | true |
|
QUEEN_QLOG_HASH_SIDECARS |
boolean | true |
|
QUEEN_QLOG_SHARDS |
integer | 0 (one log per queue; at most 4096) |
|
QUEEN_RAFT_DIR |
string | /var/lib/queen/raft |
|
QUEEN_RAFT_DISK_HIGH_PCT |
number (percent) | 85.0 |
|
QUEEN_RAFT_DISK_LOW_PCT |
number (percent) | 80.0 |
|
QUEEN_RAFT_ELECTION_MS |
integer | 1000 on a cluster, 150 on a single node |
|
QUEEN_RAFT_FORCE_RECOVER |
integer | (empty) |
|
QUEEN_RAFT_GROUPS |
integer | 1 (at most 64) |
|
QUEEN_RAFT_HEARTBEAT_MS |
integer | 100 on a cluster, 50 on a single node |
|
QUEEN_RAFT_JOIN |
boolean | false |
|
QUEEN_RAFT_LISTEN |
string | 0.0.0.0 at this node's raft port in QUEEN_RAFT_PEERS |
|
QUEEN_RAFT_MEMBER_HOLD_DISK_PCT |
number (percent) | QUEEN_RAFT_DISK_LOW_PCT (80) |
|
QUEEN_RAFT_MEMBER_HOLD_S |
integer | 21600 |
|
QUEEN_RAFT_NODE_ID |
string | 1 (a number from 1, or ordinal) |
|
QUEEN_RAFT_PEERS |
string | (empty: a single voter) |
|
QUEEN_RAFT_PLANNER_QUEUE_DEPTH |
integer | 1024 |
|
QUEEN_RAFT_PURGE_HOLD_S |
integer | 600 |
|
QUEEN_RAFT_READY_LAG_MS |
integer | 2000 |
|
QUEEN_RAFT_READY_QUORUM_MS |
integer | 5000 |
|
QUEEN_RAFT_REPLICATOR |
string | local (openraft for a cluster) |
|
QUEEN_RAFT_TOKEN |
string | (empty) |
|
QUEEN_TENANT_GROUPS |
string | (empty: placement by hash) |
Standby cluster
| Variable | Type | Default | Also read as |
|---|---|---|---|
QUEEN_LINK_HOLD_DISK_PCT |
number (percent) | QUEEN_RAFT_DISK_LOW_PCT (80) |
|
QUEEN_LINK_HOLD_S |
integer | 3600 |
|
QUEEN_LINK_NAME |
string | standby-<the standby's id> |
|
QUEEN_LINK_PIPELINE |
integer | 64 |
|
QUEEN_LINK_SEED |
integer | (unset: no node takes a seed) |
|
QUEEN_LINK_SOURCE |
string | (unset: this cluster follows no source) |
|
QUEEN_LINK_SOURCE_TOKEN |
string | (unset) |
|
QUEEN_LINK_STANDBY |
boolean | false |
|
QUEEN_LINK_TOKEN |
string | (unset: the node serves no standby) |
Authentication
| Variable | Type | Default | Also read as |
|---|---|---|---|
JWT_ALGORITHM |
string | HS256 |
|
JWT_AUDIENCE |
string | (empty) |
|
JWT_CLOCK_SKEW |
integer | 30 |
|
JWT_ENABLED |
boolean | false |
|
JWT_ISSUER |
string | (empty) |
|
JWT_JWKS_REFRESH_INTERVAL |
integer | 3600 |
|
JWT_JWKS_TIMEOUT_MS |
integer | 5000 |
|
JWT_JWKS_URL |
string | (empty) |
|
JWT_PUBLIC_KEY |
string | (empty) |
|
JWT_ROLE_ADMIN |
string | admin |
|
JWT_ROLE_READ_ONLY |
string | read-only |
|
JWT_ROLE_READ_WRITE |
string | read-write |
|
JWT_ROLE_WRITE_ONLY |
string | write-only |
|
JWT_ROLES_ARRAY_CLAIM |
string | roles |
|
JWT_ROLES_CLAIM |
string | role |
|
JWT_SECRET |
string | (empty) |
|
JWT_SKIP_PATHS |
string | /health,/metrics/prometheus,/metrics,/ |
Consume and long-poll
| Variable | Type | Default | Also read as |
|---|---|---|---|
DEFAULT_SUBSCRIPTION_MODE |
string | new |
|
DEFAULT_TIMEOUT |
integer | 30000 |
POP_DEFAULT_TIMEOUT_MS |
POP_DEFAULT_TIMEOUT_MS |
integer | 30000 |
Security and tenancy
| Variable | Type | Default | Also read as |
|---|---|---|---|
QUEEN_ENCRYPTION_KEY |
string | (empty) |
|
QUEEN_TENANCY_HEADER |
boolean | false |
Ephemeral queues
| Variable | Type | Default | Also read as |
|---|---|---|---|
QUEEN_EPHEMERAL_BURST |
integer | 10_000 |
|
QUEEN_EPHEMERAL_IMPLICIT_IDLE_S |
integer | 300 |
|
QUEEN_EPHEMERAL_LEASE_S |
integer | 30 |
|
QUEEN_EPHEMERAL_MAX_BYTES |
integer | 256 * 1024 * 1024 |
|
QUEEN_EPHEMERAL_QUEUE_MAX_BYTES |
integer | 16 * 1024 * 1024 |
|
QUEEN_EPHEMERAL_QUEUE_MAX_LENGTH |
integer | 10_000 |
|
QUEEN_EPHEMERAL_RATE |
integer | 5000 |
|
QUEEN_EPHEMERAL_REQUIRE_GRANT |
boolean | the value of QUEEN_TENANCY_HEADER (so: false) |
|
QUEEN_EPHEMERAL_RETRY_LIMIT |
integer | 5 |
Embedded proxy and Kafka facade
| Variable | Type | Default | Also read as |
|---|---|---|---|
QUEEN_KAFKA_EMBEDDED |
boolean | false |
|
QUEEN_KAFKA_SHUTDOWN_GRACE_MS |
integer | 5000 |
|
QUEEN_KAFKA_THREADS |
integer | min(4, cores / 2), at least 1 |
|
QUEEN_PROXY_EMBEDDED |
boolean | false |
|
QUEEN_PROXY_PORT |
string | (empty: the proxy fronts PORT) |
S3 sink
| Variable | Type | Default | Also read as |
|---|---|---|---|
QUEEN_S3_EMBEDDED |
boolean | false |
|
QUEEN_S3_SHUTDOWN_GRACE_MS |
integer | 30000 |
|
QUEEN_S3_THREADS |
integer | cores / 4, clamped to 1..=2 |
PostgreSQL connectors
| Variable | Type | Default | Also read as |
|---|---|---|---|
QUEEN_PG_CONNECTORS |
boolean | true |
Logging
| Variable | Type | Default | Also read as |
|---|---|---|---|
LOG_LEVEL |
string | info |
|
QUEEN_LOG_JSON |
boolean | false |
|
RUST_LOG |
string | info |
LOG_LEVEL |
QUEEN_RAFT_PLANNER_QUEUE_DEPTH is printed at boot and changes nothing else; the planner’s command
channel is QUEEN_RAFT_COMMAND_QUEUE_DEPTH, below.
Engine tuning
The replicated log, the planner and the consumption engine read their settings where they are
used, so the generator above does not see them. These are the ones worth knowing. The defaults are
the result of measuring on real load, so change one when a measurement tells you to, and change
one at a time. A numeric setting that is not a positive integer keeps its default; a switch that is
on by default turns off only with 0, false, off or no.
Planner and log
| Variable | Default | Effect |
|---|---|---|
QUEEN_PLANNER_THREADS |
8 (1 to 64) |
Threads that plan a cycle’s commands, the leader’s planning thread included. Commands that share no partition, queue setting, KV key or timer plan at the same time; 1 plans every command on one thread. The consumption engine splits its checkpoints into as many commands. QUEEN_LANES, its old name, is read when it is unset. |
QUEEN_RAFT_PIPELINE |
8 |
Log entries in flight at once on the leader. |
QUEEN_RAFT_BATCH_MAX_CMDS |
4096 |
Commands one planning cycle drains. |
QUEEN_RAFT_BATCH_MAX_BYTES |
4194304 (4 MiB) |
Estimated bytes one planning cycle drains. |
QUEEN_RAFT_ENTRY_MAX_BYTES |
100663296 (96 MiB) |
The largest planned command: a push to one partition, one KV or timers call, one positions list. A larger one is refused. |
QUEEN_RAFT_COMMAND_QUEUE_DEPTH |
16384 |
The planner’s command channel. |
QUEEN_RAFT_REQUEST_ID_WINDOW_S |
60 |
How long a committed command’s outcome answers a retry under the same request id. |
QUEEN_RAFT_REQUEST_EXPIRE_FAST_MS |
10 |
How often the leader looks whether 256 recorded outcomes have left QUEEN_RAFT_REQUEST_ID_WINDOW_S, and retires what has in its next cycle. Fewer wait for the 10 s tick. 0 leaves everything to that tick, which retires ten seconds of outcomes at once. |
QUEEN_RAFT_ANSWER_AT_COMMIT |
on | Answer pushes and acks when their entry commits, without waiting for it to apply on the leader. |
QUEEN_RAFT_DEDUP_INDEX |
txns |
How each append’s transactionId hashes are indexed: txns (one row per append), segment (read back from the queue log) or rows. |
QUEEN_RAFT_ROWS_WINDOW |
on | A push’s index row leaves memory when it leaves the queue’s dedup window (never before 900 s), whether or not the message is still retained; older messages are read through the queue log’s own index. Needs cluster version 6. Off: a row stays for as long as its message. |
QUEEN_QLOG_DIRX |
on | Keep the directory that says which file of a queue log holds a partition’s offsets, so a read of an old message does not ask every file. Off: no new directory file is built. |
QUEEN_QLOG_HASH_SIDECARS |
on | Write a hash sidecar beside each sealed queue-log file (about 16 bytes a message), so a restart refills the dedup rows without reading the files. Off: a restart reads every file the rows need, and existing sidecars are not used. |
Admission
| Variable | Default | Effect |
|---|---|---|
QUEEN_RAFT_ADMIT_MAX_MB |
the larger of 128 MiB and (QUEEN_RAFT_PIPELINE + 2) × QUEEN_RAFT_BATCH_MAX_BYTES |
The byte budget for writes waiting to be planned. 0 turns admission off. |
QUEEN_RAFT_ADMIT_HOLD_MS |
15000 |
How long a write waits for room before it is refused with 429 overloaded. Jittered by 25% either way; the Retry-After is 1 to 5 s. |
QUEEN_RAFT_ADMIT_FWD_HOLD_MS |
2000 |
The same wait for a command a follower forwarded, never more than half of what its caller has left. |
Consumption engine
| Variable | Default | Effect |
|---|---|---|
QUEEN_CONSUME_CHECKPOINT_MS |
5 |
How often the leader logs the cursor rows that changed. A pop or an ack is answered once the checkpoint holding its change has committed. |
QUEEN_CONSUME_CHECKPOINT_EAGER |
on | A pop or an ack that waits for a change no checkpoint holds yet has the next checkpoint taken at once when none is in flight, instead of at the next QUEEN_CONSUME_CHECKPOINT_MS tick. 0 waits for the tick. What an answer waits for is the same either way. |
QUEEN_CONSUME_FAST |
off | 1, true, on or yes answers pops and acks before their checkpoint commits. A leader change can then lose a lease or an ack you were told about. |
QUEEN_CONSUME_LEADER_LEASE_MS |
400 |
The engine serves only while its node leads and has heard from a quorum within this. |
QUEEN_CONSUME_TXN_TTL_MS |
30000 |
The longest a transaction holds the cursors it acks or positions. |
QUEEN_CONSUME_ROWS_PER_COMMAND |
4096 |
Cursor rows one checkpoint command carries. |
QUEEN_CONSUME_IDLE_UNLOAD_S |
600 |
A whole-queue group’s partition that holds nothing (no lease, nothing to deliver, every change committed) for this long leaves the leader’s memory; the next message on it loads it back from its cursor row. 0 keeps every one. |
QUEEN_RAFT_MAX_CLOCK_SKEW_MS |
500 |
The clock difference between nodes that lease exclusivity allows for. A new leader serves no pops or acks for one checkpoint interval plus this. |
QUEEN_RAFT_POP_REPLY_MARGIN_MS |
50 |
A pop this close to its deadline is answered empty and never claimed for. |
QUEEN_FETCH_TOPIC_WAKE_MS |
5 |
A POST /api/v1/fetch long poll, and so a Kafka Fetch, that has read nothing answers empty once it has waited this long and another partition of a queue it reads was written on the node, so a Kafka client can fetch again the partitions it left out. 0 keeps it waiting for its own partitions. |
Cluster
| Variable | Default | Effect |
|---|---|---|
QUEEN_RAFT_CLIENT_OFFLOAD |
on | Every node serves its own clients and sends the leader only prepared commands. Off, a follower forwards whole HTTP requests. Required for QUEEN_RAFT_GROUPS above 1. |
QUEEN_RAFT_FOLLOWER_ANSWER_AT_DONE |
on | A follower answers a push or an ack once it knows the entry committed, before applying it. Pops and pushes with a duplicate still wait for the local apply. |
QUEEN_RAFT_FWD_STREAMS |
4 (1 to 64) |
Long-lived streams a follower forwards prepared commands over. |
QUEEN_RAFT_CLUSTER_VERSION_MS |
1000 |
How often the leader compares the cluster’s data format version with what every member reads, and raises it once all read the new one. A raise is one-way: older builds refuse the data from then on. 0 never raises it, which keeps a rollback open while a new release bakes. |
QUEEN_EPHEMERAL_MEMBER_TTL_MS |
4000 (at least 200) |
A member the leader has not heard from for this long owns no ephemeral partition. |
QUEEN_RAFT_MEMBER_HOLD_S |
21600 (6 hours) |
How long the leader keeps its log for a member that is away, from the entry the member had, so that it catches up from the log when it comes back. Past it, or past the disk limit below, the leader purges, and the member gets a snapshot of what lies above its own log. |
QUEEN_RAFT_MEMBER_HOLD_DISK_PCT |
QUEEN_RAFT_DISK_LOW_PCT (80) |
The fullness of the leader’s volume past which it stops keeping its log for absent members. |
Standby cluster
The nine QUEEN_LINK_* variables in the table above set up a
standby cluster and what its source keeps for it. That page says
what each one does. A cluster with none of them set is neither a standby nor read by one.
Apply and storage
| Variable | Default | Effect |
|---|---|---|
QUEEN_RAFT_APPLY_SHARDS |
4 (at most 64) |
Threads that apply partition-keyed effects in parallel. Node-local: the replicated state is the same at every value. |
QUEEN_RAFT_DURABLE_EVERY_MS |
250 |
How often the store checkpoint is written to disk. It bounds what a restart replays; no answer waits for it. |
QUEEN_RAFT_DURABLE_EVERY_BYTES |
268435456 (256 MiB) |
…or after this many bytes, whichever comes first. |
QUEEN_RAFT_DURABLE_PHASE_MS |
from the node’s raft id | Where in that period a node of a cluster writes its checkpoint, so that the nodes do not all write theirs at the same instant. A number of milliseconds sets it; off leaves the node on its own timer. |
QUEEN_RAFT_CHECKPOINT_FLUSH_STEP_MB |
8 |
The megabytes of the store file a checkpoint hands to the disk at a time before its sync, so that the raft log’s own sync does not wait behind the whole checkpoint. 0 hands it over in one go. Linux only. |
QUEEN_RAFT_CHECKPOINT_TXNS |
unset | From cluster version 7, a checkpoint writes a push’s index row without the 16-byte hashes of its transactionIds: they are in the push’s message record in the queue log, which is kept as long as the row, and a boot puts them back from there before it replays (storage). whole writes them into the checkpoint, as before 2.4.0. With the txns dedup index and the queue logs on only. |
QUEEN_RAFT_SEGMENT_BYTES |
67108864 (64 MiB) |
The size at which a queue-log file rolls. |
QUEEN_RAFT_QLOG_ZSTD_LEVEL |
1 |
zstd level for queue-log payloads; 0 stores them raw. |
QUEEN_QLOG_LANES |
1 (1 to 64) |
Queue-log lanes per queue. Read only when the data directory is created. |
QUEEN_QLOG_SHARDS |
0 (0 to 4096) |
Shared queue logs. 0 gives every queue a log of its own; K maps every queue onto one of K shared logs, the layout for thousands of queues: a write fsyncs at most K files, and files fill at the rate of all the queues in them. Read only when the data directory is created. |
QUEEN_QLOG_COMPACT_MIN_DEAD_PCT |
unset | Rewrite a sealed file once this percentage of it is dead; the raft entries it carries count as dead. Unset: a per-queue log file on its first dead message or once half of it is entries, a shared one at 50%. |
QUEEN_QLOG_RECLAIM_BOOST |
4 |
How many times bigger a reclaim pass is, in files judged, partitions looked up, time and rewrites, while the last pass left work (it ran out of its budget, or rewrote a file). 1 to 64; 1 keeps every pass at 256 files, 200 ms and one rewrite. |
QUEEN_QLOG_SEAL_AGE_S |
600 |
An active file holding data this old is sealed so retention can reclaim it, once retention has a dead message in it or it holds an eighth of a full file; 0 never seals by age. |
QUEEN_QLOG_READ_AHEAD_MB |
1 |
When a fetch finds a record out of the page cache, the kernel is asked for that record and for this many MiB of the partition’s records after it. 0 turns it off. |
QUEEN_QLOG_ENTRY_HASHES |
unset | From cluster version 7, an entry record leaves out the transactionId hashes of the appends whose message records are written with it, in the same log and the same write; a read puts them back from those records and checks the result against the entry record’s checksum (storage). keep writes them in the entry record, as before 2.4.0. |
QUEEN_STORE_SCRUB_EVERY_S |
21600 |
How often the whole store is re-verified in the background; 0 turns the scrub off. |
QUEEN_STORE_SCRUB_ROWS_PER_S |
2000 |
The scrub’s pace. |
QUEEN_RAFT_RETENTION_SCAN_PER_S |
50000 |
Partitions the leader’s retention scanner walks per second. |
PARTITION_CLEANUP_SECONDS |
unset | How long a partition that retention has emptied (no message, no dead letter, no lease) must go unwritten before it is deleted, in seconds, at least 60. Unset, PARTITION_CLEANUP_DAYS (30) applies. Never shorter than the queue’s dedup window (at least 900 s), so a repeated push still finds the partition’s hashes. A workload that opens a partition per entity (a trace, a session) keeps fewer of them with a short age. |
Other
| Variable | Default | Effect |
|---|---|---|
QUEEN_TIMERS_MAX_PAYLOAD_BYTES |
1048576 (1 MiB) |
The decoded payload ceiling of POST /api/v1/timers. |
QUEEN_CELL_ID |
unset | The cluster’s name on the dashboard. Unset, a hash of the membership. |
QUEEN_RAFT_METRICS |
on | The pipeline timing and admission families on /metrics/prometheus. |
The Kafka facade’s own settings (QUEEN_KAFKA_ADDR, QUEEN_KAFKA_ADVERTISED_ADDR,
QUEEN_KAFKA_PEERS, SASL, the dedup window of the topics it creates) are in the
Kafka reference.
Embedded proxy
QUEEN_PROXY_EMBEDDED=true runs the multi-tenant proxy inside the broker process. It takes over the
public port (PORT) and calls the broker router in process, with the broker’s own JWT off and the
tenancy header on, so the proxy is the only way in. With QUEEN_PROXY_PORT set to another port,
the proxy serves that port and PORT serves the bare broker, for clients, scrapers and probes
inside your network; that port must not face the internet. Plans and limits are on
tenants, and how to expose a node safely is on security.
| Variable | Default | Effect |
|---|---|---|
QUEEN_PROXY_PORT |
unset | Give the proxy its own port (see above). |
QUEEN_TLS_CERT, QUEEN_TLS_KEY |
unset | PEM file paths. Set both to serve TLS on the proxy’s listener. |
QUEEN_PROXY_ENFORCE |
false |
false is shadow mode: rate limits and the queue and partition counts are computed, logged and metered but not refused. The body cap and the storage and monthly message quotas are enforced either way. |
QUEEN_PROXY_TENANT_HEADER |
true |
Send each cluster’s broker tenant to the broker in x-queen-tenant. Off, every cluster shares the broker’s default tenant. |
QUEEN_PROXY_CP_TOKEN |
unset | Turns on the control-plane API. Unset, /api/cp/* and /metrics* answer 404 on the proxy’s port. |
QUEEN_PROXY_PUBLIC_URL |
unset | The public base URL: OAuth callbacks are built on it, and the session audience and allowed origin default to it. |
QUEEN_PROXY_SHARED_HOSTS |
empty | Hostnames that front many clusters, where the cluster comes from the credential, not the Host. |
QUEEN_PROXY_DEFAULT_CLUSTER |
unset | Development only: the cluster a Host that names none falls back to. |
QUEEN_PROXY_DEV_INSECURE |
false |
Development only: skip authentication. |
QUEEN_PROXY_MAX_BODY_BYTES |
16777216 (16 MiB) |
The largest body the proxy reads on the routes it buffers: push, transaction, /configure, DLQ replay, the streams cycle, KV batches and ephemeral push. A larger body gets 413 payload_too_large. Other routes go to the broker, where QUEEN_MAX_BODY_BYTES applies. |
QUEEN_PROXY_UPSTREAM_TIMEOUT_MS |
35000 |
How long a call to the broker may take. |
QUEEN_PROXY_UPSTREAM_CONNECT_TIMEOUT_MS |
5000 |
Connect timeout to the broker. |
QUEEN_PROXY_LONGPOLL_MAX_MS |
90000 |
How long the proxy waits for a long-poll pop at most, plus QUEEN_PROXY_LONGPOLL_MARGIN_MS; the broker’s own wait is not shortened (limits). |
QUEEN_PROXY_LONGPOLL_MARGIN_MS |
10000 |
Time the proxy gives a long-poll pop beyond its own timeout before it gives up on the broker. |
QUEEN_PROXY_JWT_SECRET |
unset | HS256 secret for session tokens. |
QUEEN_PROXY_JWT_ED25519_PEM, QUEEN_PROXY_JWT_ED25519_PUB_PEM |
unset | Ed25519 signing key, and a public key for a node that only verifies. |
QUEEN_PROXY_JWT_ED25519_PREV_PUB_PEM, QUEEN_PROXY_JWT_PREV_SECRET |
unset | The key you are rotating away from, for verifying only, in the same algorithm: sessions and client tokens it signed keep working while new ones get the new key. The JWKS lists both. |
QUEEN_PROXY_JWT_ISS |
queen-proxy |
Session token issuer. |
QUEEN_PROXY_JWT_AUD |
the host of QUEEN_PROXY_PUBLIC_URL |
Session token audience; none is enforced when both are unset. |
QUEEN_PROXY_JWT_TTL_S |
86400 |
Session lifetime. |
QUEEN_PROXY_COOKIE_NAME |
queen_session |
Session cookie name. |
QUEEN_PROXY_COOKIE_DOMAIN |
unset | Session cookie domain. |
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET |
unset | Sign-in with Google. |
GOOGLE_ALLOWED_DOMAINS |
empty (any verified account) | Google Workspace domains allowed to sign in. |
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET |
unset | Sign-in with GitHub. |
QUEEN_PROXY_AUTOPROVISION |
false |
true creates an account on first OAuth sign-in, in the tenant QUEEN_PROXY_AUTOPROVISION_TENANT. |
QUEEN_PROXY_DEFAULT_ROLE |
viewer |
The role an auto-provisioned user gets; an unknown value falls back to viewer. |
QUEEN_PROXY_OPERATOR_ENABLED |
false |
Allow the operator capability on this node at all. |
QUEEN_PROXY_OPERATORS |
unset | Emails that hold the operator flag, synced at boot. Set but empty revokes every operator. |
QUEEN_PROXY_BOOTSTRAP_TENANT |
unset | At first boot, create this tenant and its cluster (plan QUEEN_PROXY_BOOTSTRAP_PLAN, default dev) with an admin QUEEN_PROXY_BOOTSTRAP_EMAIL (default admin@localhost), password QUEEN_PROXY_BOOTSTRAP_PASSWORD. |
QUEEN_PROXY_BOOTSTRAP_API_KEY |
unset | With the bootstrap tenant, also register this API key with every scope. |
QUEEN_PROXY_STORAGE_REFRESH_MS |
10000 (at least 500) |
How often the storage quota is re-evaluated. |
QUEEN_PROXY_RECONCILE_MS |
60000 |
How often the queue registry reconciles with the broker’s inventory. |
QUEEN_PROXY_METER_FLUSH_MS |
15000 |
How often usage is written. |
QUEEN_PROXY_SPOOL_DIR |
./queen-proxy-spool |
Where usage is spooled while the KV does not answer. |
QUEEN_PROXY_USAGE_KEEP_DAYS |
90 |
Days of per-minute usage kept. |
QUEEN_PROXY_STALE_GRACE_MS |
600000 |
How long a cached cluster may be served past its TTL while the store does not answer. |
QUEEN_PROXY_REVOCATION_STRICT |
false |
true refuses a session when the revocation lookup itself fails. |
QUEEN_PROXY_REVOCATION_SWEEP_MS |
3600000 |
How often expired revoked-token rows are dropped; 0 turns the sweep off. |
QUEEN_PROXY_AUTH_HOST |
false |
Sign-in host mode: OAuth callbacks are built only on QUEEN_PROXY_PUBLIC_URL, never on the request’s Host. |
QUEEN_PROXY_AUTH_PORTAL_URL, QUEEN_PROXY_AUTH_PORTAL_LABEL |
unset | On a node that only verifies sessions, where to send people to sign in, and the link text. |
QUEEN_PROXY_OAUTH_STATE_SECRET |
the JWT HS secret, else a random key per process | Signs the OAuth state. Set it when several nodes serve sign-in. |
QUEEN_PROXY_CELL_MAX_PARKED |
5000 |
Long-poll pops this node holds open for all tenants together; beyond it a waiting pop gets 429. |
QUEEN_PROXY_ROLLUP_MS |
3600000 (at least 1000) |
Usage rollup and monthly quota check: the longest a cluster over its monthly allowance keeps pushing. |
QUEEN_PROXY_QUOTA_WARN_PERCENT |
80 |
The share of the monthly message quota at which the control plane is told. |
QUEEN_PROXY_KEY_TOUCH_MS |
10000 (at least 1000) |
How often the last-use time of API keys is written. |
QUEEN_PROXY_INVAL_POLL_MS |
1000 (at least 100) |
How often the cache invalidation feed is read. |
QUEEN_PROXY_REGISTRY_PERSIST_MS |
1000 |
How often newly admitted queues are written to the registry. |
QUEEN_PROXY_SHUTDOWN_DRAIN_MS |
5000 |
The longest the usage drain may hold a stopping node. |
Edge
The edge applies to everything the proxy serves. The data plane has no per-IP rate limit by default, because a fleet of producers behind one NAT would otherwise be throttled as one client.
| Variable | Default | Effect |
|---|---|---|
QUEEN_EDGE_MAX_CONNS |
20000 |
Accepted connections beyond this are closed at once. |
QUEEN_EDGE_MAX_BODY_BYTES |
67108864 (64 MiB) |
The limit for proxy handlers that read their body through an extractor. The data-plane routes and /api/cp read their bodies themselves, so the caps that apply to them are QUEEN_PROXY_MAX_BODY_BYTES, QUEEN_MAX_BODY_BYTES and 1 MiB on /api/cp. |
QUEEN_EDGE_WEB_MAX_BODY_BYTES |
1048576 (1 MiB) |
Body cap on sign-in, the console and the operator API. |
QUEEN_EDGE_RPS_PER_IP, QUEEN_EDGE_BURST_PER_IP |
0 (off); burst twice the rate |
Per-IP rate limit on the data plane. |
QUEEN_EDGE_WEB_RPS_PER_IP, QUEEN_EDGE_WEB_BURST_PER_IP |
20, 60 |
Per-IP rate limit on the web routes. |
QUEEN_EDGE_REQUEST_TIMEOUT_MS |
60000 |
Request timeout; 0 turns it off. |
QUEEN_EDGE_TIMEOUT_EXEMPT |
empty | Path prefixes with no request timeout. |
QUEEN_EDGE_LONG_POLL_MAX_MS |
310000 |
The ceiling of a long-poll at the edge. |
QUEEN_EDGE_LONG_POLL_GRACE_MS |
10000 |
Time a long-poll gets beyond its own timeout. |
QUEEN_EDGE_HEADER_READ_TIMEOUT_MS |
30000 |
The whole request head must arrive within this. |
QUEEN_EDGE_TLS_HANDSHAKE_TIMEOUT_MS |
10000 |
TLS handshake timeout. |
QUEEN_EDGE_MAX_HEADERS |
100 |
Headers per request. |
QUEEN_EDGE_MAX_HEADER_BYTES, QUEEN_EDGE_MAX_HEADER_VALUE_BYTES |
65536, 16384 |
Header size limits. |
QUEEN_EDGE_MAX_URI_BYTES |
8192 |
URI length limit. |
QUEEN_EDGE_SHUTDOWN_GRACE_MS |
25000 |
How long open connections get to finish at shutdown. |
QUEEN_EDGE_TRUSTED_PROXIES |
empty | Addresses whose forwarded client IP is believed. |
QUEEN_EDGE_REAL_IP_HEADER |
unset | The header that carries the client IP from a trusted proxy. |
QUEEN_EDGE_MAX_TRACKED_IPS |
100000 |
Clients the rate limiter tracks. |
QUEEN_EDGE_IPV6_PREFIX |
64 |
IPv6 clients are counted per prefix of this length. |
QUEEN_PUBLIC_ORIGINS |
the origin of QUEEN_PROXY_PUBLIC_URL |
Origins allowed to send cookie-carrying requests. |
QUEEN_EDGE_SESSION_COOKIES |
empty | More cookie names treated as session cookies, beside QUEEN_PROXY_COOKIE_NAME and its cell variants. |
QUEEN_EDGE_CORS_ORIGINS, QUEEN_EDGE_CORS_HEADERS |
none; authorization, content-type, x-request-id |
CORS. |
QUEEN_EDGE_HSTS, QUEEN_EDGE_HSTS_MAX_AGE_S |
auto, 31536000 |
HSTS: auto, on or off. auto sends it only on HTTPS the proxy can see: its own TLS, or X-Forwarded-Proto: https from a trusted proxy. Behind a load balancer that ends TLS, set on. |
Password sign-in is throttled per IP and per account: after the free failures, each further
failure doubles a backoff that starts at QUEEN_LOGIN_BACKOFF_BASE_MS.
| Variable | Default | Effect |
|---|---|---|
QUEEN_LOGIN_FREE_FAILURES_IP |
10 |
Failures from one IP, within the window, before backoff starts. |
QUEEN_LOGIN_FREE_FAILURES_ACCOUNT |
5 |
Failures on one account, within the window, before backoff starts. |
QUEEN_LOGIN_BACKOFF_BASE_MS |
1000 |
The first backoff step. |
QUEEN_LOGIN_LOCKOUT_S |
900 |
The longest the backoff grows. |
QUEEN_LOGIN_WINDOW_S |
900 |
A key whose last failure is older than this starts over. |
QUEEN_LOGIN_MAX_TRACKED |
100000 |
IPs and accounts tracked, each. |