Configuration Guide

Every field in HAProxy UI belongs to one of four inspectors, each mirroring a section of haproxy.cfg. Each field carries operator-facing help text explaining what the directive does, in plain English.

Fields without a widget still round-trip. Anything the app does not model is preserved verbatim through rawLines / rawSections and shown in a raw-payload panel where it can still be seen and deleted. The inspector is a convenience, not a gate — nothing becomes un-editable because it has no form field.

Global inspector

Process model, identity, limits and tuning for the HAProxy process itself.

  • Process model — master-worker, nbproc, nbthread

  • Process identity — user, group, chroot, pidfile

  • Limits — maxconn, tune_ssl_default_dh_param, ssl_mode_async

  • Runtime APIs — stats socket, stats timeout, admin socket

  • Log send hostname, mailers, peers, programs, Lua loads, CPU / RSS tuning, performance options (tune.*)

Note on flag directives. master-worker is a flag with no value. It is emitted in its bare form; haproxy rejects master-worker true. The global section has no flag-only directives beyond this one, which is why its serialization helper is shaped differently from the defaults, frontend and backend helpers.

Frontend inspector

  • Bind — IPv4/IPv6, port, SSL, alpn, ciphers, client-ssl, PROXY protocol

  • ACL rules — match conditions and their actions, ordered, per bind

  • Backend switching rules — route a request to a backend based on an ACL

  • Stick tables — per-frontend counters and sessions

  • Capture — request/response capture headers

  • Monitor URI, redirects (HTTP→HTTPS, path rewrites, host swaps), default backend

Backend inspector

  • Balance mode — the ten algorithms the Dataplane v3 API accepts. See Balance Algorithms.

  • Hash type — required whenever the algorithm is hash or uri.

  • Stickiness — cookie, stick-table, learn

  • Health checks — active (TCP, HTTP, SSL) and passive (observe), expected status, body regex

  • Connection pooling — pool_max_conn, pool_low_conn, pool_purge_delay, pool_conn_name, max_reuse

  • Timeouts — connect, server, client, queue, fin, http-request, http-keep-alive, tunnel

  • Forwarded / PROXY — option forwardfor, option proxy

The HTTP-specific health-check fields (http-check method, uri, …) are shown only when the advanced check is httpchk. Selecting a different check family clears the HTTP-only fields rather than leaving contradictory directives in the config.

Server inspector

  • Identity — address, port

  • Weight & slowstart, backup & cookie

  • Track — follow another server or backend; mark down when the target is down

  • Shard — fractional client-hash routing for stickiness (0 disables)

  • Active health check — check, proto, inter, downinter, fastinter, rise, fall, observe, on_error, and the PROXY / SSL / SNI / ALPN variants

  • Agent check — agent_check, agent_addr, agent_port, agent_inter, agent_send

  • Connection caps and pool tuning, error policy (error_limit), TCP keepalive (tcp_ut), TLS to server (ssl, ssl_reuse, verify, sni, alpn, ciphers)

Paste-import

Paste up to 5 MB of an existing haproxy.cfg into the import sheet. The app parses it, previews what would change, and lets you opt out per frontend or backend — unchecking one keeps the canvas version instead of overwriting it.

  • The parser walks the modeled subset (global, defaults, frontend, backend, server) and produces canonical objects.

  • Unknown directives in known sections, and whole unrecognized sections (userlist, resolvers, peers, …), are preserved verbatim.

  • Parsing is debounced at 300 ms, so a 50k-line paste does not re-parse on every keystroke.

Draft validation

Validation runs before anything is sent. Errors are typed and attributed to the specific node and field, not surfaced as a generic failure:

  • Duplicate frontend or backend names

  • A frontend with no bind line

  • Per-server constraint violations

Absence means “inherits”

This trips people up, so it is worth stating plainly: a field left unset in the canonical model is not the same as a field set to a default value. backend.mode and backend.balance are only populated when explicitly set, so haproxy’s own defaults-section inheritance continues to work. If HAProxy UI filled in a value the user never chose, it would silently override whatever the defaults section says.

Was this article helpful?