Control HAProxy at Runtime with the Admin Socket API (2026)

HAProxy’s admin socket API lets you poke and prod its running configuration without restarting the whole damn thing.

Let’s watch it work. Imagine you have a HAProxy instance running, listening on port 80 for web traffic, and you want to gracefully take a backend server offline for maintenance.

frontend http
    bind *:80
    default_backend webservers

backend webservers
    balance roundrobin
    server web1 192.168.1.10:80 check
    server web2 192.168.1.11:80 check

You’ve got web1 and web2 serving traffic. Now, you want to disable web1 without dropping active connections or returning errors to users.

First, you need to configure the admin socket in your haproxy.cfg. Add this to your global section:

global
    # ... other global settings
    stats socket /var/run/haproxy.sock mode 660 level admin

Here, stats socket tells HAProxy to expose an admin interface. /var/run/haproxy.sock is the path to the Unix domain socket file it will create. mode 660 sets file permissions, and level admin grants full administrative privileges to users who can access this socket (typically, users in a specific group).

After reloading HAProxy (systemctl reload haproxy or kill -HUP <haproxy_pid>), you can interact with it using socat or echo and cat through the socket.

To disable web1, you’d run:

echo "disable server webservers/web1" | sudo socat stdio /var/run/haproxy.sock

What just happened? HAProxy received the disable server command. It immediately stops sending new connections to web1. Importantly, any connections already established with web1 are allowed to complete gracefully. Once all active connections to web1 have terminated, HAProxy will no longer consider it available for service. You can verify this by checking HAProxy’s stats (if you’ve enabled them separately) or by trying to access web1 directly.

To bring it back online:

echo "enable server webservers/web1" | sudo socat stdio /var/run/haproxy.sock

This command tells HAProxy to once again consider web1 for new connections. It will start sending traffic to it according to the configured load balancing algorithm.

The real power comes from understanding the various commands. You can:

show servers state: See the current status of all servers.
set server <backend>/<server> state maint: Puts a server into maintenance mode. This is similar to disable server but explicitly marks it for maintenance, which can be useful for monitoring or scripted operations.
set server <backend>/<server> state ready: Takes a server out of maintenance mode, making it available again.
show stat: Provides a wealth of information about HAProxy’s internal state, including connection counts, error rates, and server status.
clear counters <backend>/<server>: Resets the statistics for a specific server, useful for troubleshooting or performance baseline measurements.
shutdown session <session_id>: Terminate a specific, active client session. This is a more granular control than disabling a whole server.

The admin socket is not just for taking servers offline. You can dynamically change backend weights, enable/disable entire frontends or backends, and even reload the configuration from disk without a full restart. For example, to disable an entire frontend named http:

echo "disable frontend http" | sudo socat stdio /var/run/haproxy.sock

And to re-enable it:

echo "enable frontend http" | sudo socat stdio /var/run/haproxy.sock

This allows for sophisticated blue/green deployments or canary releases where you can shift traffic between versions of your application by manipulating HAProxy’s configuration on the fly. The commands are synchronous; HAProxy attempts to perform the action and returns a success or failure message back through the socket.

Many people assume that to change HAProxy’s configuration, you must restart it. This is often not true. The admin socket API provides a way to make many critical, real-time adjustments to a running HAProxy instance, including modifying server states, clearing statistics, and even reloading configuration files. This capability is crucial for maintaining high availability and performing zero-downtime maintenance.

The next thing you’ll want to explore is how to automate these socket commands using scripts or configuration management tools to build sophisticated traffic management workflows.