Configuración

Toda la configuración de EQProxy vive en un único fichero TOML con schema_version = 1. Esta página recoge las claves que existen —tipo, defecto y nota— por sección, con un ejemplo mínimo por bloque.

El esquema real es eqproxy.schema.json, regenerable con eqproxy config schema; eqproxy.toml.example es el fichero comentado que repasa las mismas claves.

Estructura del fichero

El esquema es cerrado (additionalProperties: false en todas las tablas): una clave con errata se rechaza, no se ignora. schema_version es obligatoria y solo vale 1. Las duraciones son cadenas con sufijo ("500ms", "5s", "1h"). Las rutas relativas —certificados, mapas, páginas de error, caché en disco— se resuelven desde el directorio del TOML, no desde el directorio de trabajo.

Los nombres de listener y backend son claves de tabla ([listener.web], [backend.api]). Un listener exige listen y backend; un backend exige server o servers, nunca los dos.

Global y métricas

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

Cada fase tiene su reloj y su respuesta observable; config explain imprime las dos cosas antes de que nada ocurra.

Inactividad y duración son cosas distintas: idle_timeout corta un intercambio que no se mueve; max_stream_duration, uno que se mueve pero dura demasiado.

Conexiones y límites

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

Cuando todos los servidores de un backend están en su maxconn, la petición falla de forma explícita con no_available_server y, si hay cola, espera en ella.

TLS en el 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"]

El certificado por defecto responde a los clientes sin SNI y a los nombres que ninguna entrada reclama: un nombre desconocido no hace fallar el handshake. La selección es nombre exacto y después el comodín más largo.

Reglas de enrutamiento

Cada regla de [listener.*.rules] suma condiciones (AND) y lleva exactamente una acción; el orden del array es el orden de evaluación.

[[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/"

Un 429 por rate limit es siempre explícito y suma rate_limited. El cubo es local al proceso: con varias instancias, cada una lleva el suyo.

Upstreams y balanceo

En servers, los pesos van de 0 a 256 y weight = 0 deja el servidor drenado sin tocar el resto. priority (0..=255) solo vale con backup = true y ordena los escalones de failover; all_backups y priority juntos son un error de configuración. Un source fija la IP local de salida y solo vale para destinos TCP.

[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"

Sin sección health_check, todos los servidores se consideran operativos. Una comprobación correcta no demuestra que la aplicación funcione: prueba lo que le pidas y nada más.

Caché

Solo en mode = "http" y solo si la sección existe.

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

Solo se almacenan GET con estados 200, 301, 308, 404 y 410 y sin Set-Cookie. Las respuestas servidas llevan X-Cache: HIT, MISS o REVALIDATED.

Para comprimir respuestas hay una sección aparte, [listener.*.compression]: gzip y level (1..9, 6 por defecto), brotli y brotli_quality (0..11, 5 por defecto), min_size (1024) y types.

Filtros WASM

Filtro de petición, uno por listener, solo en mode = "http". El módulo se compila al cargar la configuración: un fichero ausente, un import denegado o una exportación que falte rechazan el snapshot, no fallan por petición.

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

El plugin puede añadir, sustituir o quitar cabeceras de petición y rechazar con 400..=599; las de framing (content-length, transfer-encoding, host) están reservadas.

Mapas de datos

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

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

Un mapa se relee en caliente sin recargar la configuración: los datos nuevos entran de forma atómica y el resto del estado —contadores, cubos, pools, conexiones— sobrevive. Escribe con escritura + renombrado para que el vigilante nunca lea un fichero a medias; una actualización mal formada se rechaza, suma map_reload_failures y sigue sirviendo la última buena.

Secretos y recarga en caliente

[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"

Prefiere token_file a token: un token escrito en el TOML viaja allí donde se copia el fichero. El token de escritura debe ser distinto del de lectura; sin él, el plano entero es de solo lectura.

Plano de administración

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

Sin sección [admin] no hay plano de administración. Los endpoints, los roles y los códigos de respuesta están en API de administración.