HAProxy cheat sheet: essential commands

1. Validation and CLI #

Identifying the version and validating the integrity of your configuration.

Checking the version #

It is essential to check your binary's capabilities, especially for SSL/TLS or Lua support.

# Version simple
haproxy -v

# Version détaillée (indispensable pour le débug)
haproxy -vv

The -vv command shows the linked libraries (OpenSSL, PCRE, etc.) and the build options that may restrict some features.

Testing the configuration #

Golden rule: never reload a production service without validating the syntax. A misplaced comma can stop the service.

# -c : check mode, -f : spécifie le fichier
haproxy -c -f /etc/haproxy/haproxy.cfg

HAProxy can load several files. The order of the -f options matters because directives are read sequentially.

2. Managing the service #

Controlling the life cycle depending on your environment.

Systemd (Linux) #

Prefer reload to restart. A reload uses the USR2 signal to start a new process while letting the old one finish in-flight connections (hitless reload).

# Rechargement sans coupure
sudo systemctl reload haproxy

# Vérification du statut du service
sudo systemctl status haproxy

Docker & Docker Compose #

In a container, restarting the container cuts connections. Use the SIGHUP signal to trigger HAProxy's internal reload.

# Envoyer le signal HUP au processus 1 du conteneur
docker kill -s HUP <container_name>

# Consulter les logs de santé et de trafic
docker logs --tail 100 -f <container_name>

3. Runtime API through socat #

Interacting with HAProxy in real time through the UNIX socket.

Reading information #

The socket lets you talk directly to the engine. It must be defined in global with an admin level.

# Extraire les stats au format CSV
echo "show stat" | socat stdio /var/run/haproxy.stat

# Voir les infos de santé globale (Uptime, Process ID, etc.)
echo "show info" | socat stdio /var/run/haproxy.stat

Live actions #

These changes are immediate and don't require a reload, but they are volatile (lost at the next restart unless also written to the .cfg).

# Sortir un serveur du pool (Drain)
echo "set server web_servers/srv1 state maint" | socat stdio /var/run/haproxy.stat

# Changer dynamiquement le ratio de trafic (Weight)
echo "set server web_servers/srv1 weight 10" | socat stdio /var/run/haproxy.stat

4. Debugging #

Tools for network analysis.

Interactive mode #

The -db (disable background) mode is perfect for development. It shows all warnings and errors directly in the terminal.

haproxy -db -f /etc/haproxy/haproxy.cfg

Checking ports #

Check that HAProxy listens on the expected interfaces and ports (80, 443, 8404).

sudo ss -tlpn | grep haproxy

Conclusion #

Production tip #

Always prefer the HUP signal (or systemctl reload) to a restart to avoid rejecting in-flight client connections during a configuration update.