Configuration

All of EQProxy's configuration lives in a single TOML file with schema_version = 1. This page collects the keys that exist —type, default and note— per section, with a minimal example per block.

The real schema is eqproxy.schema.json, regenerable with eqproxy config schema; eqproxy.toml.example is the commented file that goes over the same keys.

File structure

The schema is closed (additionalProperties: false in every table): a key with a typo is rejected, not ignored. schema_version is mandatory and only 1 is valid. Durations are strings with a suffix ("500ms", "5s", "1h"). Relative paths —certificates, maps, error pages, on-disk cache— are resolved from the TOML's directory, not from the working directory.

Listener and backend names are table keys ([listener.web], [backend.api]). A listener requires listen and backend; a backend requires server or servers, never both.

Global and metrics

schema_version = 1
shutdown_grace = "10s"

[metrics]
detailed = false
max_series = 128

Listeners

[listener.web]
listen = "0.0.0.0:8080"
mode = "http"
backend = "api"
maxconn = 2048
forwarded_headers = "append"

Timeouts

Each phase has its own clock and its observable response; config explain prints both before anything happens.

Idleness and duration are different things: idle_timeout cuts an exchange that does not move; max_stream_duration, one that moves but lasts too long.

Connections and limits

[listener.web.limits]
max_head_bytes = 16384
max_headers = 100
max_body_bytes = 1048576

When every server of a backend is at its maxconn, the request fails explicitly with no_available_server and, if there is a queue, waits in it.

TLS on the listener

[listener.web.tls]
cert = "certs/fullchain.pem"
key = "certs/privkey.pem"
alpn = ["h2", "http/1.1"]

[[listener.web.tls.certs]]
cert = "certs/api.pem"
key = "certs/api.key"
names = ["api.example.com", "*.api.example.com"]

The default certificate answers clients without SNI and the names no entry claims: an unknown name does not make the handshake fail. Selection is exact name and then the longest wildcard.

Routing rules

Each rule in [listener.*.rules] adds conditions (AND) and carries exactly one action; the array order is the evaluation order.

[[listener.web.rules]]
name = "api-v1"
host = "api.example.com"
path_prefix = "/api/v1/"
use_backend = "api"
rate_limit = { rate = 10, per = "1s", burst = 20 }

[listener.web.rules.rewrite]
path_prefix_rewrite = "/api/"

A 429 from rate limiting is always explicit and adds rate_limited. The bucket is local to the process: with several instances, each one keeps its own.

Upstreams and balancing

In servers, weights range from 0 to 256 and weight = 0 leaves the server drained without touching the rest. priority (0..=255) only works with backup = true and orders the failover tiers; all_backups and priority together are a configuration error. A source sets the local outbound IP and only works for TCP destinations.

[backend.api]
balance = "leastconn"
servers = [
  { addr = "10.0.0.11:9000", weight = 3 },
  { addr = "10.0.0.12:9000", weight = 1 },
  { addr = "10.0.0.13:9000", weight = 1, backup = true },
]
maxqueue = 256
timeout_queue = "500ms"

Health checks

[backend.api.health_check]
type = "http"
interval = "2s"
fall = 3
rise = 2
http_path = "/healthz"
expect_status = "200-299"

Without a health_check section, all servers are considered operational. A correct check does not prove the application works: it tests what you ask of it and nothing more.

Cache

Only in mode = "http" and only if the section exists.

[listener.web.cache]
default_ttl = "60s"
max_memory_bytes = 67108864
disk_path = "cache/web"

Only GET with status 200, 301, 308, 404 and 410 and without Set-Cookie is stored. Served responses carry X-Cache: HIT, MISS or REVALIDATED.

To compress responses there is a separate section, [listener.*.compression]: gzip and level (1..9, 6 by default), brotli and brotli_quality (0..11, 5 by default), min_size (1024) and types.

WASM filters

A request filter, one per listener, only in mode = "http". The module is compiled when the configuration is loaded: a missing file, a denied import or a missing export reject the snapshot, they do not fail per request.

[listener.web.plugin]
path = "plugins/filter.wasm"
timeout = "50ms"
on_error = "closed"

The plugin can add, replace or remove request headers and reject with 400..=599; the framing ones (content-length, transfer-encoding, host) are reserved.

Data maps

[maps.tiers]
file = "tiers.map"
default = "free"

[[listener.web.rules]]
name = "vip-tenants"
map = { name = "tiers", header = "x-tenant", equals = "vip" }
use_backend = "vip"

A map is re-read hot without reloading the configuration: the new data enters atomically and the rest of the state —counters, buckets, pools, connections— survives. Write with write + rename so the watcher never reads a half-written file; a malformed update is rejected, adds map_reload_failures and keeps serving the last good one.

Secrets and hot reload

[admin]
unix_socket = "/run/eqproxy/admin.sock"
unix_socket_mode = "0660"
unix_socket_gid = 20
token_file = "/etc/eqproxy/admin.token"
write_token_file = "/etc/eqproxy/admin-write.token"

Prefer token_file to token: a token written in the TOML travels wherever the file is copied. The write token must differ from the read one; without it, the whole plane is read-only.

Admin plane

[admin]
listen = "127.0.0.1:9001"
token_file = "/etc/eqproxy/admin.token"
write_token_file = "/etc/eqproxy/admin-write.token"
panel = true

Without an [admin] section there is no admin plane. The endpoints, roles and response codes are in Admin API.