Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/wikioasis/salt/llms.txt

Use this file to discover all available pages before exploring further.

The haproxy Salt execution module provides runtime control of HAProxy directly through its Unix stats socket. Every function communicates with the running HAProxy process using socat — no configuration file edits, no haproxy reload, and no brief connection disruption. Changes made through this module take effect immediately and persist only until the next HAProxy restart unless you also update the pillar and re-apply the haproxy.route state.

​
Socket Configuration

The module reads the socket path from haproxy:stats_socket in pillar, with a default of /run/haproxy/admin.sock: 
# pillar
haproxy:
  stats_socket: /run/haproxy/admin.sock
All commands are sent by constructing a shell pipeline of the form: 
printf '<command>\n' | socat stdio /run/haproxy/admin.sock
A CommandExecutionError is raised if socat exits non-zero.

​
Functions

​
haproxy.status()

Returns the current state of all backend servers by parsing the output of the show stat HAProxy command. Frontend and backend aggregate rows are filtered out; only individual server rows are returned. Returns: List of dicts, each with keys backend, server, status, and weight. 
salt 'proxy*' haproxy.status
Example output: 
proxy-us-east-011.ovvin.wonet:
  - backend: mediawiki
    server: mw-us-east-011
    status: UP
    weight: '1'
  - backend: mediawiki
    server: mw-us-east-012
    status: UP
    weight: '1'
  - backend: mediawiki
    server: mw-us-east-021
    status: MAINT
    weight: '1'
The status field comes directly from HAProxy’s CSV stat output (column 18). Common values are UP, DOWN, MAINT (manually disabled via disable server), and DRAIN.

​
haproxy.depool(backend, server)

Disables a server in the specified backend by sending disable server <backend>/<server> to the stats socket. Takes effect immediately with no reload. Existing connections to the server are allowed to complete (graceful drain); no new requests are routed to it.
​
backend
string
required
The HAProxy backend name, e.g. mediawiki.
​
server
string
required
The server name as defined in the HAProxy configuration, e.g. mw-us-east-011.
Returns: Confirmation string in the format <backend>/<server> depooled. 
salt 'proxy*' haproxy.depool mediawiki mw-us-east-011
Example output: 
proxy-us-east-011.ovvin.wonet:
    mediawiki/mw-us-east-011 depooled
proxy-us-east-021.ovvin.wonet:
    mediawiki/mw-us-east-011 depooled
Depooling a server via this module affects only the live HAProxy state. The server will be automatically repooled on the next HAProxy restart unless you also update the HAProxy configuration. For deploy-time depool/repool, mwdeploy --rollout handles this automatically.

​
haproxy.repool(backend, server)

Re-enables a previously disabled server in the specified backend by sending enable server <backend>/<server> to the stats socket. Takes effect immediately.
​
backend
string
required
The HAProxy backend name, e.g. mediawiki.
​
server
string
required
The server name as defined in the HAProxy configuration, e.g. mw-us-east-011.
Returns: Confirmation string in the format <backend>/<server> repooled. 
salt 'proxy*' haproxy.repool mediawiki mw-us-east-011
Example output: 
proxy-us-east-011.ovvin.wonet:
    mediawiki/mw-us-east-011 repooled
proxy-us-east-021.ovvin.wonet:
    mediawiki/mw-us-east-011 repooled

​
haproxy.route_list()

Returns all active hostname → backend mappings from the live HAProxy routes map (/etc/haproxy/routes.map) by parsing the output of show map /etc/haproxy/routes.map. The map is used by HAProxy’s ACLs to route requests from a given Host header to the correct backend. Returns: Dict of hostname → backend. 
salt 'proxy*' haproxy.route_list
Example output: 
proxy-us-east-011.ovvin.wonet:
    wikioasis.org: mediawiki
    wiki.wikioasis.org: mediawiki
    staging.wikioasis.org: mediawiki_staging
The raw show map output includes an internal pointer prefix (0x...) on each line. The module strips this and returns only the hostname and backend values.

​
haproxy.route_set(hostname, backend)

Adds or updates a hostname → backend mapping in the live routes map. If the hostname already exists, the old entry is removed first (via del map) and the new one is added (via add map). The change takes effect immediately for all new connections.
​
hostname
string
required
The virtual hostname to route, e.g. app.example.com. Must match the Host header sent by clients.
​
backend
string
required
The HAProxy backend name to route the hostname to, e.g. mediawiki.
Returns: String in the format <hostname> -> <backend>. 
salt 'proxy*' haproxy.route_set app.example.com mediawiki
Example output: 
proxy-us-east-011.ovvin.wonet:
    app.example.com -> mediawiki
This change is live but not persisted. After a HAProxy restart, the route will be gone unless you update pillar and re-apply the haproxy.route state. See Runtime vs Persisted Changes below.

​
haproxy.route_del(hostname)

Removes a hostname route from the live routes map by sending del map /etc/haproxy/routes.map <hostname> to the stats socket. Takes effect immediately; requests to the deleted hostname will no longer match the map entry.
​
hostname
string
required
The virtual hostname to remove from the routes map, e.g. app.example.com.
Returns: String in the format <hostname> removed. 
salt 'proxy*' haproxy.route_del app.example.com
Example output: 
proxy-us-east-011.ovvin.wonet:
    app.example.com removed

​
Runtime vs Persisted Changes

HAProxy holds the routes map in memory. Changes made through this module (route_set, route_del) update the in-memory map immediately but are lost on HAProxy restart. To make a route change permanent, you must also update the pillar and apply the haproxy.route state: 
# pillar — haproxy:routes
haproxy:
  routes:
    - hostname: app.example.com
      backend: mediawiki
      active: true

# Apply the state to write /etc/haproxy/routes.map and sync the live map
salt 'proxy*' state.apply haproxy.route
The haproxy.route state writes /etc/haproxy/routes.map from pillar, then on file change clears the live in-memory map and re-adds every active entry via the socket — again, no reload required.
MethodImmediateSurvives restart
haproxy.route_set / haproxy.route_del✅ Yes❌ No
Update pillar + state.apply haproxy.route✅ Yes (via socket sync)✅ Yes
For a permanent route change in a single workflow: run haproxy.route_set to take effect immediately, update the pillar to persist it, then apply haproxy.route to confirm the file and live state are in sync.

​
Common Workflows

​
Depool a server before maintenance

# Depool from all proxies
salt 'proxy*' haproxy.depool mediawiki mw-us-east-021

# Verify it's out
salt 'proxy*' haproxy.status

# ... perform maintenance ...

# Repool
salt 'proxy*' haproxy.repool mediawiki mw-us-east-021

​
Add a new wiki vhost route

# Add live immediately
salt 'proxy*' haproxy.route_set newwiki.example.com mediawiki

# Verify the route is present
salt 'proxy*' haproxy.route_list
Then update pillar and apply the state to persist: 
salt 'proxy*' state.apply haproxy.route

​
Remove a decommissioned wiki route

# Remove from live map
salt 'proxy*' haproxy.route_del oldwiki.example.com

# Confirm removal
salt 'proxy*' haproxy.route_list
Remove the entry from pillar and re-apply haproxy.route to prevent it coming back on restart.

Build docs developers (and LLMs) love

Get started for freeTalk to us