Skip to content

Configuration: environment variables reference

The environment variables the broker, its engine and the embedded proxy read, with the default the code applies.

Updated View as Markdown

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.0

In 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.
Navigation

Type to search…

↑↓ navigate↵ selectEsc close