Configuración

Referencia de las secciones del IR nativo (TOML), campo a campo, con un ejemplo mínimo por sección. El esquema lo define el propio producto: cualquier campo no listado aquí se rechaza con unknown field. Valida siempre con exyonq validate -c <fichero>.

config_version

Obligatorio. Versiones admitidas: 1 y 2. La 2 es la actual y la única que permite include, una lista de ficheros que se fusionan con el documento principal.

config_version = 2
include = ["/etc/exyonq/tls.toml", "/etc/exyonq/sites.d/blog.toml"]

[logging]

Niveles y destinos. level acepta la sintaxis de EnvFilter: info, debug, o por objetivo (exyonq=debug,warn).

[logging]
level = "info"
format = "text"

[logging.console]
enabled = true
stream = "stdout"

[logging.access]
enabled = true

[[server]]

Un bloque por conjunto de nombres que comparten socket. listen es obligatorio; el resto, opcional.

[[server]]
listen = "0.0.0.0:8080"
server_name = ["exyonq.dev", "www.exyonq.dev"]
routes = ["site"]
proxy_protocol = { enabled = true, trusted = ["10.0.0.0/8"] }

[server.error_pages]
"404" = "/404.html"
"503" = "/maintenance.html"

[server.tls]

cert y key son obligatorios si la tabla existe. Los campos criptográficos solo se honran en el primer bloque de un listen compartido; declararlos en otro bloque es error, no un ignorado silencioso.

[server.tls]
cert = "/etc/exyonq/tls/exyonq.dev.pem"
key = "/etc/exyonq/tls/exyonq.dev.key"
strict_sni = true
protocols = ["TLSv1.2", "TLSv1.3"]
ciphers = ["TLS13_AES_256_GCM_SHA384", "TLS13_CHACHA20_POLY1305_SHA256"]
curves = ["X25519", "secp256r1"]
ocsp_stapling = "/etc/exyonq/tls/exyonq.dev.ocsp.der"
must_staple = false

[server.tls.acme]

Emisión y renovación automáticas. Solo se honra en el primer [[server]].

[server.tls.acme]
enabled = true
email = "security@exyonq.dev"
domains = ["exyonq.dev", "www.exyonq.dev"]
challenge = "http-01"

[[route]]

Campos de match:

[[route]]
name = "assets"
match = { path = "/assets", host = "exyonq.dev" }
root = "/var/www/exyonq/assets"
response_headers = [{ name = "Strict-Transport-Security", value = "max-age=31536000; includeSubDomains" }]

[route.cache_headers.by_mime]
"image/avif" = { max_age = 31536000, immutable = true }

redirect emite location tal cual, sin plantillas: una ruta por host si quieres conservar el destino. rewrite admite flag = "last" | "break" | "redirect" | "permanent" y condiciones when (path, host, query, header, header_value, todas AND). El reemplazo admite $1–$9, $uri y $host.

[[upstream]]

[[upstream]]
name = "app"
selection_policy = "least_conn"
timeout_ms = 15000
endpoints = [
  { address = "10.0.1.11", port = 8080, weight = 3 },
  { address = "10.0.1.12", port = 8080, weight = 3 },
]

[upstream.health_check]
enabled = true
path = "/health"
expect_status = [200]

[[fcgi_pool]] (FastCGI / PHP-FPM)

[[fcgi_pool]]
name = "php"
address = "/run/php/php-fpm.sock"
transport = "unix"
document_root = "/var/www/html"
max_concurrency = 16
total_timeout_ms = 120000

[modules.compression]

[modules.compression]
enabled = true
min_bytes = 256
level = 5

El resto de módulos de la misma tabla: [modules.metrics] (enabled, path = /metrics, health_path, scrape_bearer_token obligatorio si se escucha en una dirección no local), [modules.ratelimit] (enabled, requests_per_second = 100, burst = 200, zones, routes) y [modules.real_ip] (enabled, trusted, header = x-forwarded-for; con enabled = true exige al menos un CIDR de confianza).

Módulos y campos de 0.9.0

• [modules.gunzip]: enabled (off) y buffer_bytes (32 KiB); una ruta puede forzar gunzip = true|false.
• [modules.auth.routes.<ruta>]: realm y user_file (htpasswd) para auth básica.
• [modules.ratelimit.zones.<zona>]: key (ip, host o header:<nombre>), requests_per_second y burst; [modules.ratelimit.routes] asigna ruta → zona.
• [modules.sub_filter.routes.<ruta>]: rules = [{ pattern, replacement }], once (true), types (["text/html"]) y last_modified (false).
• [modules.mirror.routes.<ruta>]: destinations (rutas internas) y request_body (true).
• [modules.slice.routes.<ruta>]: size en bytes (1 KiB..1 GiB).
• En [[route]]: front_controller (script de respaldo para FastCGI) y root_mode (remainder o full-uri).

[modules.gunzip]
enabled = true

[modules.auth.routes.site]
realm = "Admin"
user_file = "/etc/exyonq/admin.htpasswd"

[modules.ratelimit]
enabled = true

[modules.ratelimit.zones.site]
key = "ip"
requests_per_second = 20
burst = 40

[modules.ratelimit.routes]
site = "site"

[modules.sub_filter.routes.site]
rules = [{ pattern = "http://old.example", replacement = "https://new.example" }]

[modules.mirror.routes.site]
destinations = ["/_mirror"]

[modules.slice.routes.site]
size = 1048576

El ejemplo junta los bloques en una sola ruta para mostrarlos; en producción se reparten entre las rutas que los necesiten.

[static.preload]

Límites de la precarga del árbol estático. Un cero en cualquiera de las tres claves desactiva la precarga entera; no significa «sin límite».

[static.preload]
max_file_bytes = 33554432
max_total_bytes = 268435456
max_entries = 4096

[static.encoding_cache] es una caché de compresión en disco, apagada por defecto: enabled, cache_dir (/var/cache/exyonq/static-encoding), level (6), min_bytes (300), max_bytes (10 MiB), max_entries (4096), max_total_bytes (1 GiB), gzip (true) y brotli (false).

[full_page_cache]

[full_page_cache]
enabled = true
default_ttl_seconds = 300
max_ttl_seconds = 3600
namespace = 4
private_cookies = ["wordpress_logged_in", "wp-postpass"]

[full_page_cache.key]
query = ["page", "p"]

[http3]

[http3]
enabled = true
provider = "s2n"

[[server]]
listen = "0.0.0.0:443"
http3_listen = "0.0.0.0:443"
server_name = ["exyonq.dev"]
routes = ["site"]

[server.tls]
cert = "/etc/exyonq/tls/exyonq.dev.pem"
key = "/etc/exyonq/tls/exyonq.dev.key"

http3_listen no se puede combinar con strict_sni, protocols, ciphers, curves, ocsp_stapling ni must_staple, ni con varios [[server]] TLS en el mismo listen: los proveedores QUIC solo consumen cert y key, y el producto prefiere rechazar la configuración antes que ignorarla.

[[map]]

Tabla de equivalencias exactas. Tope de 32 mapas y 64 entradas por mapa.

[[map]]
name = "connection_upgrade"
input = "header"
header = "Upgrade"
default = "close"
values = { "websocket" = "upgrade" }

[[route]]
name = "ws"
match = { path = "/socket" }
upstream = "app"
proxy_set_headers = [
  { name = "Connection", value = "$connection_upgrade" },
  { name = "Host", value = "$host" },
]

Las variables disponibles en plantillas son exactamente $host, $remote_addr, $request_uri, $scheme y $<map>. Cualquier otro $… es error de configuración.

[[cache_policy]]

[[cache_policy]]
name = "html"
ttl_seconds = 60

[[route]]
name = "site"
match = { path = "/" }
upstream = "app"
cache = "html"