Skip to main content
emisar

HAProxy operations

v0.1.15

Stats, server state, frontends/backends, session inventory, plus narrow mutators to enable/disable backend servers. Talks to the HAProxy admin socket. Set HAPROXY_SOCK env var on the runner host.

8 allowed by default 4 need approval by default
Pack ID
haproxy
Vendor
emisar
OS
linux
Actions
12
Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.
socat

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host 
sudo emisar pack install haproxy --hash sha256:168bc9315f9b1b2bd830eddfd33a0eb6e5f298957280a1d016d2fb2a6c134a8f

Setup

Talks to the local HAProxy admin/stats UNIX socket via socat on the runner host. There is no default — you must point HAPROXY_SOCK at the socket.

Environment

Set these on the runner host, then add each name to execution.inherit_env so the value reaches the action.

  • HAPROXY_SOCK required

    Path to the HAProxy admin/stats UNIX socket (the stats socket from haproxy.cfg).

Host access

Run these commands yourself on the runner host. Emisar shows and copies setup recipes; it never runs them.

Read and write the configured HAProxy admin socket.

haproxy.show_infohaproxy.show_stathaproxy.show_servers_statehaproxy.show_poolshaproxy.show_errorshaproxy.show_sesshaproxy.show_maphaproxy.show_backendhaproxy.show_frontendhaproxy.enable_serverhaproxy.disable_serverhaproxy.set_maxconn

Run the Emisar service as root

Grant access 
sudo install -d -m 0755 /etc/systemd/system/emisar.service.d
printf '%s\n' '[Service]' 'User=root' 'Group=root' | sudo tee /etc/systemd/system/emisar.service.d/10-haproxy-host-access.conf >/dev/null
sudo systemctl daemon-reload
sudo systemctl restart emisar
Verify access 
test "$(systemctl show emisar --property=User --value)" = root

Impact: Every Emisar action on this runner executes as root. An HAProxy admin-level socket can change backend availability and runtime limits beyond the actions in this pack.

Notes

  • HAPROXY_SOCK only reaches an action when the runner allowlists it in execution.inherit_env — the action env is scrubbed to PATH/LANG/LC_ALL/TERM by default. There is NO fallback: unset, every action hands socat an empty address and fails with an unknown device/address error rather than naming the missing allowlist entry.
  • The socket must be declared with level admin in haproxy.cfg for the enable/disable/set mutators to work.

Verify it works

Runs haproxy.show_info, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host 
sudo emisar pack verify haproxy

Install and configure a pack walks through the whole sequence on a host.

Actions 12 total

View on GitHub
  • haproxy.disable_server exec high High — service-affecting

    disable server <backend>/<server>

    Stop sending new traffic to one backend server (in-flight requests continue).

    View source on GitHub
  • haproxy.enable_server exec high High — service-affecting

    enable server <backend>/<server>

    Re-enable one backend server that was administratively disabled; it returns to rotation and live traffic reaches it again (subject to health checks).

    View source on GitHub
  • haproxy.set_maxconn exec high High — service-affecting

    set maxconn frontend <name> <N>

    Live-update the maxconn cap on one frontend without a reload; lowering it below the current connection count turns away new connections until the count drops.

    View source on GitHub
  • haproxy.show_backend exec low Low — read-only or trivially reversible

    show backend

    List backend names.

    View source on GitHub
  • haproxy.show_errors exec high High — service-affecting

    show errors

    List recent request/response errors captured by HAProxy. Use to debug 503s. Each entry is the verbatim captured buffer of the failing transaction — the request line and every header, so cookies, `Authorization` headers, and the leading body bytes come back as-is. That content is client-supplied and no redaction list enumerates it, so this is approval-gated. Read-only.

    View source on GitHub
  • haproxy.show_frontend exec low Low — read-only or trivially reversible

    Frontend stats (show stat, type=frontend)

    Show per-frontend stats (status, sessions, bytes, denied, errors) as CSV. There is no `show frontend` Runtime-API command, so this uses `show stat -1 1 -1` — the stat dump filtered to type=frontend (the bitmask 1 = frontend).

    View source on GitHub
  • haproxy.show_info exec low Low — read-only or trivially reversible

    show info

    Show HAProxy version, uptime, process stats, conn rate, mem usage.

    View source on GitHub
  • haproxy.show_map exec low Low — read-only or trivially reversible

    show map

    List all loaded `map` files (the lookup tables HAProxy uses for routing).

    View source on GitHub
  • haproxy.show_pools exec low Low — read-only or trivially reversible

    show pools

    Show internal memory pool usage. Use to spot leaks.

    View source on GitHub
  • haproxy.show_servers_state exec low Low — read-only or trivially reversible

    show servers state

    Show persisted server state — health, weight, admin overrides. Read this before reloading config to know what state should be preserved.

    View source on GitHub
  • haproxy.show_sess exec low Low — read-only or trivially reversible

    show sess

    List in-flight sessions (one row per active connection).

    View source on GitHub
  • haproxy.show_stat exec low Low — read-only or trivially reversible

    show stat

    Show per-proxy + per-server stats (sessions, queues, bytes, errors, response times).

    View source on GitHub
← Back to registry
Pack reference  Publish your own