One file, explicit boundaries

Model

server:
  threads: 0                         # 0: one worker per logical CPU
  graceful_shutdown_timeout: 30s
  plugin_dir: /etc/omlb/plugins
  cache_max_entries: 10000

listeners: []                        # client-facing HTTP listeners
upstreams: {}                        # named pools referenced by routes
routes: []                           # first matching route wins
plugins: []                          # named native or WASM filters
admin: { enabled: true, address: "127.0.0.1:9090" }
observability:
  metrics: { enabled: true, address: "127.0.0.1:9091" }
  access_log: { enabled: true }
  log_level: info
  log_format: pretty

The root sections are server, listeners, upstreams, routes, plugins, admin, observability, plus optional tls, l4, security, webui, and ha. Duration values use human-readable forms such as 2s, 30s, and 5m.

Some sections have defaults, but listeners and routes do not. A configuration with no listener is rejected. Named routes and plugins must be unique; every route must reference an existing upstream and declared plugin; an upstream must use exactly one source: static backends, managed Docker, DNS SRV, or Consul discovery.

Validate before deployment

# Validate the file and exit. Use the installed binary in deployment.
omlb --check --config /etc/omlb/omlb.yaml

# A reload is also triggered after an atomic replacement of the watched file.
# Watcher debounce: 500 ms; polling fallback: 2 s.

Validation checks addresses, duplicate names, pool and plugin references, route shape, regular expressions, static certificate files, TLS and ACME consistency, L4 settings, HA safety constraints, and security input. A non-zero result means do not deploy. It reports validation problems before the server starts.

Automatic reload, narrowly applied

OMLB watches the configuration file’s parent directory and also fingerprints the file every two seconds, covering atomic editor saves and single-file container bind mounts. It coalesces changes, reloads the base plus overlay, validates them, and keeps the previous accepted configuration on any error.

Hot-applied: routes (including matches, rewrites, cache, response, compression, and body limits), declared plugin chains and plugin configuration, and each existing pool’s retry and timeout policy.

Graceful restart required: listener addresses and protocol settings; the set of pools; static backends, weights, algorithm, health checks, outlier policy, and discovery/managed-pool settings; TLS; L4; admin, metrics, Web UI, HA, security, server settings, and log settings. These are rejected on reload rather than partially taking effect.

Safe change procedure

1. Render the candidate YAML and any referenced files on the target host.
2. Run omlb --check --config ….
3. Classify the change using the reload boundary above. For a hot change, atomically replace the file and inspect logs or /status. For a bootstrap change, use the service manager’s graceful restart path.
4. Verify the intended route or backend state with a real request before removing the previous path.