Skip to content

Configuration

View as Markdown

durable-server is configured entirely by flags; there is no config file. durable-server --help is the same list in the binary. Defaults shown are what the flag carries.

The required two, and the directory that matters

Section titled “The required two, and the directory that matters”
Flag Default What it sets
--journal <dir> data/journal the append-only journal — the runner’s only state. Local disk, one writer ever; see deployment
--listen <addr> 127.0.0.1:58300 bind address. Loopback is the default; bind wider only behind a real key and a proxy plan
--handler name=URL — repeatable: the allowlist a step may name. Unregistered names are refused at submit (409 unregistered_handler)

Plus the environment: DURABLE_API_KEY (required at startup, ≥ 32 chars) and DURABLE_READ_KEY (optional, ≥ 32 chars, must differ). Authentication covers what each opens.

Flag Default Bound
--step-timeout-ms 20000 per-attempt deadline on a handler call (the domain caps it at 30 s)
--reply-timeout-ms 10000 how long an API call waits on the engine before 503 timeout — a stuck disk must not hang every request
--max-live-runs 100000 non-terminal runs admitted; past it, submits are 503 at_capacity
--max-index-bytes ~512 MiB approximate bytes of retained runs in memory; same refusal. Sized for a 2 GB host
--max-in-flight 32 handler calls (attempts + probes) concurrently in flight
--max-dispatch-per-tick 64 dispatches per 50 ms scheduler tick — the first-step dispatch rate is at most ~1280/s
Flag Default Bound
--max-connections 512 connections served at once; extras wait in the accept queue. Keep below ulimit -n minus 64
--header-timeout-ms 10000 a request head must arrive within this
--body-deadline-ms 30000 a request body must finish within this (408 otherwise)
--write-stall-ms 10000 a response write that stalls this long drops the connection
--max-connection-secs 600 a keep-alive connection’s maximum age
--max-requests-per-connection 100 the Nth answer carries Connection: close
--drain-timeout-secs 30 SIGTERM/SIGINT: finish in-flight requests, then let the engine make its decisions durable, before exiting
Flag Default Bound
--reserve-bytes 67108864 (64 MiB) free space that must stay on the journal filesystem; below it submits are 503 no_space, /ready is false, compaction and backup refuse what won’t fit
--backup-root <dir> — enables POST /admin/backup; without it, 403 backups_disabled
--compact-every-secs 0 automatic compaction period; 0 means only on request (POST /admin/compact)
--max-snapshot-bytes 2147483648 (2 GiB) a compaction whose snapshot would exceed this is refused 409 snapshot_over_budget
--journal-format — print the highest journal record version this binary can read, then exit — the deploy kit’s format guard compares it to the journal’s before an upgrade or rollback

One address shouldn’t be able to hold every connection or spend every request: these flags bound per-client pressure at the edge. All on by default — 0 disables any of them.

Flag Default Bound
--rate-limit-per-addr 100 per second requests one client address may start; a token bucket with a one-second burst, the address table itself bounded. Over it, 429 rate_limited with Retry-After
--rate-limit-v6-prefix 64 prefix bits an IPv6 client is keyed by — a /64 holds 2⁶⁴ addresses, so keying the full address would let one client mint unlimited buckets
--max-conns-per-addr 64 connections one untrusted address may hold at once; past it the socket is closed at accept
--max-conns-per-proxy 4096 connections one peer inside the trusted ranges may hold — a proxy’s edge legitimately carries many real clients at once (the global --max-connections still bounds everything)
--trusted-proxy <CIDR> — repeatable: the proxy ranges the server believes. A client’s address comes from CF-Connecting-IP only when the peer is inside a trusted range — anyone can set that header, so it is believed from no one else

Inside a /48 the per-address IPv6 buckets also share a /48 aggregate at 10× the rate, so a host hopping addresses inside its own prefix stays one client and a whole /48 can’t hide a flood; IPv4-mapped IPv6 addresses count as IPv4. 429 rate_limited is retryable — back off by Retry-After, resubmit with the same op_key.

A second instance with a low rate shows the shape — five requests a second per address, a ten- request burst, then the honest refusal:

Terminal window
./target/release/durable-server --journal journal-limits --listen 127.0.0.1:58301 \
--rate-limit-per-addr 5 --trusted-proxy 10.0.0.0/8 >limits-server.log 2>&1 &
LIMITED=$!
for _ in $(seq 1 100); do curl -sf http://127.0.0.1:58301/health >/dev/null && break; sleep 0.1; done
for i in $(seq 1 10); do
curl -s -o /dev/null -w '%{http_code} ' -H "Authorization: Bearer $DURABLE_API_KEY" http://127.0.0.1:58301/jobs
done; echo
curl -si -H "Authorization: Bearer $DURABLE_API_KEY" http://127.0.0.1:58301/jobs | sed -n '1p;/retry-after/Ip;/rate_limited/p'
kill $LIMITED 2>/dev/null; wait $LIMITED 2>/dev/null || true; rm -rf journal-limits limits-server.log
200 200 200 200 429 429 429 429 429 429
HTTP/1.1 429 Too Many Requests
retry-after: 1
{"error":"rate limited","code":"rate_limited"}
Flag Default Bound
--ui-dir <dir> — serve the built Inspector assets at /inspector
--open-reads off serve GET /jobs* without a key — loopback listen only (refused at startup otherwise), and never behind a proxy; authentication explains why
Terminal window
DURABLE_API_KEY="$(openssl rand -hex 32)" \
DURABLE_READ_KEY="$(openssl rand -hex 32)" \
durable-server --journal /var/lib/durable/journal --listen 127.0.0.1:58300 \
--handler invoices=http://127.0.0.1:58320/invoices \
--handler reports=http://127.0.0.1:58321/reports \
--backup-root /var/lib/durable/backups --compact-every-secs 3600

The loopback listen is deliberate: TLS terminates at the proxy in front, and the read surface still wants the keys. Security is the checklist this start assumes.

Was this page helpful?

Either answer opens a short issue on GitHub, so you can say what worked or what was missing.